CLI Reference

Complete reference for all Vulnetix CLI commands, flags, and usage patterns.

Commands

vulnetix (root command)

Run vulnerability management tasks against the Vulnetix backend.

vulnetix

The root command runs an authentication healthcheck.

Global Flags:

vulnetix auth

Manage authentication credentials for the Vulnetix API.

vulnetix auth [login|status|verify|logout] [flags]

auth login

Authenticate with Vulnetix. Interactive by default when run in a terminal.

# Interactive browser device flow (prompts for storage)
vulnetix auth login --store keyring

# Non-interactive login with an ApiKey
vulnetix auth login --api-key <KEY> --org-id <UUID> --store keyring

# Non-interactive login with a SigV4 secret
vulnetix auth login --secret <SECRET> --org-id <UUID> --store keyring

# Non-interactive login with a Bearer token (org resolved server-side)
vulnetix auth login --token <TOKEN> --store keyring

Flags:

--api-key, --secret, and --token are mutually exclusive. Running vulnetix auth without a subcommand also triggers login.

See Authentication for storage backends, precedence, file permissions, and rotation.

auth status

Show current authentication state, including the credential source, method, masked key, and Package Firewall .netrc status.

vulnetix auth status

auth verify

Verify that stored credentials can authenticate with the Vulnetix API. Does not modify credentials.

# Verify stored credentials
vulnetix auth verify

# Verify with explicit API endpoint
vulnetix auth verify --base-url https://api.vdb.vulnetix.com/v1

auth logout

Remove stored credentials from all file-based stores.

vulnetix auth logout

vulnetix package-firewall

Configure package managers to use the Vulnetix Package Firewall.

vulnetix package-firewall go [flags]

package-firewall go

Configure Go to use https://packages.vulnetix.com with .netrc authentication.

vulnetix package-firewall go
vulnetix package-firewall go --dry-run

This command writes a machine packages.vulnetix.com entry to .netrc, persists GOPROXY and GOAUTH=netrc in your shell configuration, and updates detected project files at the git root (.env, .envrc, Makefile).

Flags:

package-firewall uninstall

Remove the configuration written for one, some, or every ecosystem. Needs no authentication — it operates on local files only. See Uninstall.

vulnetix package-firewall uninstall npm pypi        # named ecosystems
vulnetix package-firewall uninstall --all            # every supported ecosystem
vulnetix package-firewall uninstall --except aur     # all but the named ones
vulnetix package-firewall uninstall --purge          # every ecosystem + the shared netrc credential

Exactly one selector is required: positional ecosystem(s), --all, or --except. The shared ~/.netrc credential is kept unless --remove-credentials or --purge is given.

Flags:

vulnetix config

Manage Vulnetix configuration. This manages the Package Firewall per-organization policy and ecosystem mirrors, the org-wide Quality Gate scan-enforcement policy, and the Quality Gate end-of-life severity buckets. The organization is resolved from your authenticated session (vulnetix auth login).

vulnetix config set package-firewall [ecosystem] [url] [flags]
vulnetix config get package-firewall [flags]
vulnetix config set quality-gate [flags]
vulnetix config get quality-gate [flags]
vulnetix config set eol-policy [flags]
vulnetix config get eol-policy [flags]

config set package-firewall

Two forms, distinguished by positional arguments.

Policy form (no positionals) — updates the org-wide policy. Each call is a partial update; only the flags you pass change.

vulnetix config set package-firewall --cvss-threshold 8.0 --block-malware true --cooldown-days 7

Mirror form (<ecosystem> <url>) — adds, updates, enables, or disables one upstream mirror.

# Add a mirror; priority auto-increments per ecosystem when omitted
vulnetix config set package-firewall npm https://registry.npmjs.org

# Pin a priority, or toggle a mirror by ecosystem + url
vulnetix config set package-firewall npm https://npm.internal.example --priority 0
vulnetix config set package-firewall npm https://registry.npmjs.org --disable

Both forms share --base-url (default https://api.vdb.vulnetix.com) and -o, --output (pretty, json).

config get package-firewall

Print the org-wide policy and every mirror across all ecosystems.

vulnetix config get package-firewall
vulnetix config get package-firewall -o json

config set quality-gate

Set the org-wide Quality Gate scan-enforcement policy. When a member runs vulnetix scan (or sca, sast, …) while authenticated, every value you set here overrides the equivalent scan flag — org policy always wins, even over an explicitly-passed flag. Settings you leave unset fall back to the caller’s flag or the builtin default.

Each call is a partial update — only the flags you pass change; everything else keeps its current value. To clear a setting back to “not enforced”, pass null as the flag’s value (e.g. --severity null) — members then fall back to their own scan flag or the builtin default.

vulnetix config set quality-gate --severity high --block-malware true --cooldown 3

Every flag takes a value (e.g. --block-malware true). Pass null to unset a setting entirely for the org — the value is cleared and members fall back to their own scan flag or the builtin default:

vulnetix config set quality-gate --severity null --cooldown null

Omitting a flag leaves its stored value unchanged. Both this command and config get quality-gate share --base-url (default https://api.vdb.vulnetix.com) and -o, --output (pretty, json).

config get quality-gate

Print the org-wide Quality Gate enforcement policy. Settings the organization never configured render as not set (the caller’s flag or builtin default applies for those).

vulnetix config get quality-gate
vulnetix config get quality-gate -o json

config set eol-policy

Set the four end-of-life calendar-quarter severity buckets of the Quality Gate. These map an upcoming or past EOL date to a synthetic finding severity during vulnetix scan (opt-in via the org policy). The buckets are literal calendar quarters (Q1 Jan–Mar, Q2 Apr–Jun, Q3 Jul–Sep, Q4 Oct–Dec); a date is classified by which quarter it lands in. This is not a per-product mapping — it is the four shared time buckets.

Each call is a partial update.

vulnetix config set eol-policy \
  --next-quarter-severity low \
  --this-quarter-severity medium \
  --within-30-days-severity high \
  --retired-severity critical

Use skip to suppress findings for a bucket entirely. Both this command and config get eol-policy share --base-url (default https://api.vdb.vulnetix.com) and -o, --output (pretty, json).

config get eol-policy

Print the four EOL calendar-quarter severity buckets.

vulnetix config get eol-policy
vulnetix config get eol-policy -o json

vulnetix upload

Upload a security artifact file (SBOM, SARIF, VEX, CSAF) to Vulnetix for processing.

vulnetix upload --file <path> [flags]

The file format is auto-detected from content and extension but can be overridden. Files larger than 10MB are uploaded using chunked transfer. Authentication uses stored credentials or environment variables.

Flags:

Examples:

# Upload with stored credentials
vulnetix upload --file sbom.cdx.json

# Upload with explicit org ID
vulnetix upload --file report.sarif --org-id "123e4567-e89b-12d3-a456-426614174000"

# Override format detection
vulnetix upload --file report.json --format sarif

# JSON output for scripting
vulnetix upload --file sbom.cdx.json --json

vulnetix gha

GitHub Actions artifact management. Designed for use within GitHub Actions workflows.

gha upload

Collect and upload all artifacts from the current GitHub Actions workflow run to Vulnetix.

vulnetix gha upload [flags]

This command:

1. Collects all artifacts from the current workflow run via the GitHub API
2. Downloads and extracts each artifact
3. Uploads each file to Vulnetix using the standard upload API
4. Reports pipeline UUIDs for each uploaded file

Requires: GITHUB_TOKEN, GITHUB_REPOSITORY, GITHUB_RUN_ID environment variables.

Flags:

The API base URL is not a flag on gha; both subcommands go through the shared client, so use VULNETIX_API_URL if you need to point them elsewhere.

gha status

Report on the ingestion snapshots produced by a workflow run, or on a single snapshot by UUID.

vulnetix gha status                    # current run (GITHUB_RUN_ID)
vulnetix gha status --run-id <RUN_ID>
vulnetix gha status --uuid <UUID>

Flags:

vulnetix license

Analyze package licenses for conflicts, policy compliance, and risk. See the full License Command Reference for details.

vulnetix license [flags]

Subcommands:

vulnetix license policy init|show|validate      # category-based policy
vulnetix license exceptions add|ls|check        # approved exceptions

A policy classifies licences by category and attaches a severity to each, which stays correct when a dependency introduces a licence nobody enumerated. The built-in default reproduces exactly what the evaluator did before policies existed, so adopting one is deliberate rather than something an upgrade does to your build. Exceptions carry approver, grounds and expiry; an expired one stops applying and says so.

License analysis also runs automatically during vulnetix scan (disable with --no-licenses).

vulnetix aibom

Discover AI coding agents/assistants and AI usage, and emit a CycloneDX AI Bill of Materials. See the full AIBOM Command Reference and the AIBOM overview.

vulnetix aibom [path] [flags]

Detection is catalog-driven (42+ tools, AI SDKs, model-name extraction). The environment pass records variable names only — never their values.

vulnetix cbom

Discover cryptographic usage in code and config and emit a CycloneDX Cryptography Bill of Materials (CBOM) with post-quantum posture. See the full CBOM Command Reference and the CBOM overview.

vulnetix cbom [path] [flags]

Detection is catalog-driven across source, config, certificates and crypto libraries. Algorithm spellings are case/separator-insensitive (SHA256/Sha256/SHA_256 → one SPDX algorithm); each is classified quantum-safe / quantum-vulnerable / deprecated / hybrid with a per-country approval matrix.

vulnetix cdx

Generate one standalone CycloneDX document containing package SBOM inventory, AIBOM components and CBOM components. The command is offline: no VDB lookup, upload, memory update, quality gate, image pull or container daemon is used. Discovery spans manifests and lockfiles, installed package trees, container package databases, Dockerfiles, CI/CD pipeline files, shell scripts and recipes, and the packages compiled into binaries (Go build info, Rust cargo auditable, JVM archives). Each component carries the same metadata sca records, including the dependency graph and licenses.

vulnetix sbom is an alias for this command — CycloneDX is the preferred format, and a future SPDX generator will be its own command. See the full CDX Command Reference.

vulnetix cdx [path] [flags]
vulnetix sbom [path] [flags]   # alias

vulnetix bom

Read SBOM documents, including ones this CLI did not produce. Where cdx generates a CycloneDX document from a working tree, bom reads documents back in: CycloneDX 1.0–1.7, SPDX 2.2/2.3, and in-toto attestation envelopes — the shape Syft and BuildKit emit for container SBOMs, which a plain bomFormat check misses entirely.

Everything parsed normalises into one CycloneDX model, so an SPDX file and a CycloneDX file diff against each other and appear side by side in a corpus query. See the full BOM Command Reference.

vulnetix bom import <file|->              # parse and report; --out re-emits as CycloneDX
vulnetix bom validate <file>              # structure plus per-field completeness
vulnetix bom diff <before> <after>        # the change-review gate
vulnetix bom merge <file> <file...>
vulnetix bom tree <file>                  # --invert answers "what pulls this in"
vulnetix bom enrich <file> --out <file>   # resolve licences, attach vulns, apply VEX

vulnetix bom ls     --from ./sboms/       # corpus inventory
vulnetix bom where  <pkg> --from ./sboms/ # blast radius, direct vs transitive
vulnetix bom skew   --from ./sboms/       # inconsistent versions across services
vulnetix bom search <query> --from ./sboms/

vulnetix vex

Read, validate, merge and apply VEX statements — OpenVEX 0.2.0, CycloneDX VEX and CSAF 2.0 VEX — including ones this CLI did not write. That is the case VEX exists for: an upstream publishing “this CVE does not affect the configuration we ship” reaching your scan. See the full VEX Command Reference.

vulnetix vex apply --vex vendor.openvex.json --bom sbom.cdx.json
vulnetix vex ls --vex ./vex/
vulnetix vex validate --vex ./vex/
vulnetix vex merge --vex ./vex/ --out merged.openvex.json

Matching is not exact equality on (vulnerability, purl) — that is why VEX so often appears to do nothing, and it fails silently. Version ranges, unversioned products, aliases and URL-form identifiers are all handled, and every match records why it matched.

--vex-file and --no-vex apply the same statements during a scan, in one place before the gates, so every gate honours VEX by construction. Suppressed findings are annotated, never deleted, and counted separately.

vulnetix attest

Verify signatures and in-toto provenance on artefacts you consume. Reads what cdx --sign writes and anything else in those formats. See the full Attest Command Reference.

vulnetix attest verify sbom.cdx.json
vulnetix attest verify sbom.cdx.json --strict
vulnetix attest verify sbom.cdx.json --identity 'https://github.com/acme/repo/...' --issuer github

The Sigstore public-good root is built in, so the certificate chain is validated by default, as cosign does it. --trusted-root is an override for a private deployment, resolving through SIGSTORE_ROOT_FILE and .vulnetix/trusted-root.pem first — and the output names whichever anchor answered.

vulnetix scan

Run every analysis in one pass. scan is an orchestrator: each pass is owned by its own subcommand (sca, sast, secrets, containers, iac, license, malscan, aibom, cbom) and scan composes them into one set of results, one SBOM and one quality-gate verdict. --evaluate-* selects a subset; --no-* switches a pass off. See the full Scan Command Reference for details.

vulnetix scan [flags]

vulnetix sca

Run only Software Composition Analysis — vulnerability analysis on package manifests plus CI/CD and shell install commands. All other features (SAST, licenses, secrets, containers, IaC) are disabled. See the SCA Command Reference.

vulnetix sca [flags]

Equivalent to vulnetix scan --evaluate-sca --no-sast --no-secrets --no-containers --no-iac --no-licenses.

When --block-malware (or the org blockMalware policy) is in effect, sca also runs the in-process malscan pass over the installed dependencies and gates on any locally-detected malware.

--vex-file, --no-vex, --policy-file, --exceptions-file and the deployment-context flags are registered on every member of the scan family — scan, sca, sast, secrets, containers, iac — and honoured by all of them.

vulnetix fix

Resolve vulnerable dependencies to safe versions, apply the change with the project’s own package manager, and rescan to confirm the finding is gone. This is the owner of remediation: --sca-autofix on the scan family triggers the same pipeline in-pass. vulnetix autofix is an alias. See the full Fix Command Reference.

vulnetix fix [path] [flags]

vulnetix report

Render the results of the last scan from .vulnetix/sbom.cdx.json — no discovery, no parsing, and by default no network calls at all. scan --from-memory is a deprecated alias for it. See the full Report Command Reference.

vulnetix report [path] [flags]

vulnetix malscan

Scan the project’s locally-installed dependencies for malware in-process — STIX IOC filesystem scan, manifest/install-script pattern detection, IOC extraction, and known-bad artifact hashing — and emit SARIF evidence. Complements --block-malware (a known-malicious-package policy lookup) by inspecting the installed bytes themselves. See the full Malscan Command Reference.

vulnetix malscan [path] [flags]

Exit code 1 on any malware found. Also runs as a pass inside scan (default on) and sca (when --block-malware/org policy is in effect).

vulnetix jail

Gate the pipeline on the organisation’s policy over the repository’s accumulated state — vulnerabilities past their remediation window, dependencies past end of life, strategic migrations that have not landed, hygiene categories that regressed. Distinct from the quality gate, which grades a single scan’s findings. See the full Jail Command Reference.

vulnetix jail [flags]

Exit 0 clear, 1 jailed, 2 usage error, 3 indeterminate (the backend state a rule needs is stale or missing). Exit 3 is deliberately not exit 1: a breach is fixed by a developer, missing coverage by whoever owns the CI configuration. Subcommands explain, list and exempt inspect and waive without gating. Also available as a --jail flag on every scan-family command.

vulnetix sast

Run only Static Application Security Testing. All other features are disabled. See the SAST Command Reference.

vulnetix sast [flags]

Equivalent to vulnetix scan --evaluate-sast --no-sca --no-secrets --no-containers --no-iac --no-licenses.

vulnetix secrets

Run only secret detection — identifies hardcoded credentials, API keys, and tokens. All other features are disabled. See the Secrets Command Reference.

vulnetix secrets [flags]

Equivalent to vulnetix scan --evaluate-secrets --no-sast --no-sca --no-containers --no-iac --no-licenses.

vulnetix containers

Run only container file analysis — checks Dockerfiles and Containerfiles, and can inspect supplied rootfs/archive inputs for installed package DBs and ELF binaries. All other features are disabled. See the Containers Command Reference.

vulnetix containers [flags]

Equivalent to vulnetix scan --enable-containers --no-sast --no-sca --no-secrets --no-iac --no-licenses.

vulnetix iac

Run only Infrastructure as Code analysis — checks Terraform HCL and Nix files. All other features are disabled. See the IaC Command Reference.

vulnetix iac [flags]

Equivalent to vulnetix scan --evaluate-iac --no-sast --no-sca --no-secrets --no-containers --no-licenses.

vulnetix ignore

Manage suppression (“ignore”) rules for scanner findings. Aliased suppress. See the full Ignore / Suppress Command Reference.

vulnetix ignore add [flags]     # create a rule
vulnetix ignore list [flags]    # list active rules
vulnetix ignore remove [flags]  # deactivate a rule
vulnetix ignore sync            # sync rules with the org backend

A rule is anchored by at least one of --rule (rego rule id), --finding (CVE / vuln id), or --file, and can be scoped by --category and typed with --type (false_positive, wont_fix, risk_accepted, mitigated, deferred, rego_rule, nosec). Use --reason to record why and --expires-in to auto-expire it. A finding is suppressed only when every anchor matches. Rules live in .vulnetix/memory.yaml and work offline; authenticated, they sync org-wide. Inline nosec comments in code are also honoured — see the reference.

vulnetix triage

Fetch vulnerability alerts from external providers (e.g. GitHub Dependabot) and enrich them with remediation intelligence from the Vulnetix VDB.

vulnetix triage [flags]
vulnetix triage status [flags]

Supported providers: github (Dependabot alerts via the gh CLI)

Flags:

For each alert the triage command fetches:

• A context-aware remediation plan (upgrade path, verification steps)
• Fix data from registry, distribution, and upstream source in parallel

Subcommands:

triage status

Verify that provider CLI tools are installed, authenticated, and functional.

vulnetix triage status [--format text|json]

Flags:

Examples:

# Interactive TUI (default)
vulnetix triage

# Triage a specific repository
vulnetix triage --repo owner/repo

# Include dismissed alerts, output as JSON
vulnetix triage --all --format json

# Check GitHub CLI auth and repo detection
vulnetix triage status

# Check status as JSON
vulnetix triage status --format json

Prerequisites: The github provider requires the gh CLI to be installed and authenticated (gh auth login).

vulnetix vdb

Interact with the Vulnetix Vulnerability Database (VDB) API. See the full VDB Command Reference for all subcommands and detailed usage.

vulnetix vdb <subcommand> [flags]

Tree-sitter reachability

vulnetix vdb vuln and the remediation flows automatically perform tree-sitter reachability analysis against your project, recording exactly which files (and line ranges) match the vulnerable pattern. Control with --reachability=direct|transitive|both|off (default both). See the Reachability Analysis section for the full feature overview, Languages for the 17 bundled grammars, and Internals for how the CGo cross-compile is structured.

vulnetix version

Print the version number of Vulnetix CLI.

vulnetix version [flags]

Also checks for available updates and prints a notice if a newer version exists.

Flags:

Examples:

# Full version info (with update check)
vulnetix version

# Just the version number, e.g. for scripting
vulnetix version --short

vulnetix update

Update the Vulnetix CLI to the latest release from GitHub.

vulnetix update

Checks the GitHub Releases API for the latest version, then downloads and replaces the current binary in-place. Binaries built from source (via go build or make dev) are not updated — use your build toolchain instead.

Behavior:

• If already up to date: prints Already up to date (vX.Y.Z).
• If a newer version is available: prints the upgrade path and performs the in-place update
• If built from source: exits with an error indicating that go build should be used

Examples:

# Check for and apply the latest update
vulnetix update

vulnetix triage

Triage vulnerability alerts from multiple providers (e.g. GitHub Dependabot) with integrated remediation intelligence from the Vulnetix Vulnerability Database.

vulnetix triage [flags]
vulnetix triage status      # Check provider CLI health

The triage command fetches vulnerability alerts from external providers, enriches each alert with VDB data (remediation plans, fix availability across registry/distribution/source), and presents them in an interactive TUI or text/JSON output.

Flags:

Examples:

# Interactive TUI with auto-detected repo
vulnetix triage

# Specify a repo and include dismissed alerts
vulnetix triage --repo owner/repo --all

# Non-interactive text output
vulnetix triage --format text

# JSON output for scripting
vulnetix triage --repo owner/repo --format json

# Check provider CLI health
vulnetix triage status

triage status

Verify that provider CLI tools (e.g. gh) are installed, authenticated, and can detect the current repository.

# Text output (default)
vulnetix triage status

# JSON output for scripting
vulnetix triage status --format json

Flags:

--provider is a flag on vulnetix triage, not on triage status; it defaults to vulnetix and accepts github.

Output (text):

  GitHub CLI Status
──────────────────────────────────────────

  ✔ gh binary   : /usr/bin/gh
  ✔ authenticated: octocat
     Host         : github.com
     Token source : OAuth Token
     Token scopes : repo, workflow
  ✔ repo detected : owner/repo

vulnetix completion

Generate shell autocompletion scripts.

vulnetix completion [bash|zsh|fish|powershell]

Authentication

Full coverage lives in Authentication. Summary:

Methods

SigV4 validates via a JWT token exchange with the VDB API, then derives the request credential as HMAC-SHA256(secret, orgID).

Credential Storage

Override the home directory with --store-dir DIR or VULNETIX_CREDENTIALS_DIR. If no OS keychain backend is found, --store keyring warns and falls back to home.

Credential Precedence

The CLI loads credentials in this order (first complete match wins):

1. VULNETIX_API_TOKEN (Bearer)
2. VULNETIX_API_KEY + VULNETIX_ORG_ID (ApiKey)
3. VVD_ORG + VVD_SECRET (SigV4)
4. Project dotfile: .vulnetix/credentials.json
5. Home directory: ~/.vulnetix/credentials.json
6. .netrc / _netrc machine packages.vulnetix.com
7. Embedded community credential (VDB read-only, community rate limits)

Flags apply to the auth login command that writes a credential; they are not part of this load chain. Inspect the winner with vulnetix auth status.

Global Flags

These flags are available on the root command and inherited by subcommands:

vulnetix --version prints the bare version. vulnetix version prints the full report (commit, build date, and the versions of the bundled malscan-engine, vdb-cyclonedx and OPA modules).

Environment Variables

Exit Codes

Common Usage Patterns

Basic Usage

# Run authentication healthcheck
vulnetix

Artifact Upload

# Upload an SBOM
vulnetix upload --file sbom.cdx.json

# Upload SARIF from a scanner
semgrep --sarif > results.sarif && vulnetix upload --file results.sarif

# Upload via the upload command with format override
vulnetix upload --file report.json --format sarif --json

CI/CD Integration

# GitHub Actions
vulnetix gha upload --org-id "$VULNETIX_ORG_ID"

# GitLab CI
vulnetix upload --file results.sarif

# Jenkins
vulnetix upload --file results.sarif