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:

gha status

Check the processing status of uploaded artifacts by transaction ID or artifact UUID.

vulnetix gha status --txnid <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]

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 scan

Walk the local directory tree, parse package manifests, and query the VDB for vulnerabilities — no files are uploaded. See the full Scan Command Reference for details.

vulnetix scan [flags]
vulnetix scan status <scan-id> [flags]

vulnetix sca

Run only Software Composition Analysis — vulnerability analysis on package manifests. 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.

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 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. 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:

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