Subcommand Reference for CI

Every platform page links here rather than restating this. Read it once.

Installing in CI

One command, on every platform that has a shell:

curl -fsSL https://cli.vulnetix.com/install.sh | sh

It installs to /usr/local/bin, falling back to $HOME/.local/bin when that is not writable. Pin a release in CI:

curl -fsSL https://cli.vulnetix.com/install.sh | sh

On minimal images, install the script’s dependencies first — alpine ships without curl, bash, tar, or CA certificates:

apk add --no-cache bash ca-certificates curl tar

Via Go, note the /v3 module suffix; the module cannot be fetched without it:

go install github.com/vulnetix/cli/v3@latest

Authenticating in CI

Set two environment variables from your platform’s secret store. That is the whole setup.

Then, as the first step of the job:

vulnetix auth verify

It reads the credential, calls the API, exits non-zero on failure, and writes nothing.

Do not run vulnetix auth login on an ephemeral runner. Environment variables sit at the top of the credential precedence chain, persist nothing, and disappear with the job; a login step writes a plaintext credentials file into the workspace for no benefit.

Do not store an ApiKey in VULNETIX_API_TOKEN. That variable holds a Bearer token, outranks everything else, and an ApiKey sent as a bearer credential is rejected. See Authentication in CI/CD.

What Each Subcommand Writes

Results land under .vulnetix/ in the scanned directory whether or not you ask for a copy elsewhere. Each command uploads its own findings to Vulnetix automatically when authenticated.

Choosing the Output Flag

Three different behaviours. Getting this wrong is the most common mistake in a CI config.

# Two artifacts from one pass
vulnetix scan -o dist/results.sarif -o dist/sbom.cdx.json

# CBOM and AIBOM take a different flag
vulnetix cbom --output-file dist/cbom.cdx.json

# license takes neither
vulnetix license && cp .vulnetix/sbom.cdx.json dist/licenses.cdx.json

--format / -f on the scan family is deprecated; use --output.

Quality Gates

Gates are opt-in. Without a gate flag the command reports findings and exits 0.

vulnetix scan --severity high --block-malware --block-eol --exploits active

Most CI systems have a way to report a breach without blocking the merge — GitLab’s allow_failure: true, Jenkins’ catchError, GitHub’s continue-on-error. Prefer that to lowering the gate.

Uploading Third-Party Artifacts

The scan subcommands publish themselves. upload exists for reports produced by other tools.

vulnetix upload --file reports/semgrep.sarif
vulnetix upload --file reports/syft.spdx.json

The report is recorded under the name and version of the tool that produced it, in the category inferred from the report, with the same findings, triage and VEX records a first-party Vulnetix scan produces. The format is read from the file’s content rather than its name, because checkov and kics both write results.sarif.

Vulnetix accepts SARIF, CycloneDX and SPDX. Anything else is refused, naming the tool’s own SARIF flag where it has one:

$ vulnetix upload --file sonarqube-issues.json
Error: sonarqube-issues.json is not a format Vulnetix ingests (detected "json").
Vulnetix accepts SARIF, CycloneDX and SPDX.
SonarQube can emit SARIF: use its sonar.sarifReportPaths export.

Reports Vulnetix’s own scanners wrote are refused too: the subcommand that produced one published it when it ran, so republishing would record the same scan twice.

In GitHub Actions prefer vulnetix gha upload, which publishes every report a workflow run produced in one call.

Pipeline Context Is Automatic

The CLI detects GitHub Actions and GitLab CI from their environment variables and attributes findings to the right repository, commit, branch, and merge/pull request without any flags. On other platforms it falls back to reading the local git checkout.

You never pass --org-id on a machine where the environment credentials are set.