Scan Command Reference

The scan command walks your project directory, parses package manifests locally, extracts package-manager install commands from CI/CD and shell files, and queries the Vulnetix VDB API to identify vulnerable dependencies. No file contents are ever uploaded to any server. Results are saved to .vulnetix/ and printed to your terminal.

Credentials are optional. When no credentials are configured the community fallback is used automatically.

Scan Is An Orchestrator

scan runs every analysis in one pass. It owns none of them: each is owned by its own subcommand, and scan composes those owners so a single invocation produces one coherent set of results, one SBOM and one quality-gate verdict.

Passing any --evaluate-* / --enable-containers flag switches scan to opt-in mode: only the named passes run. --no-* always wins.

Every pass behaves exactly as its own subcommand does — the same code runs either way, so scan --evaluate-licenses --allow MIT and license --allow MIT reach the same verdict. Two things are deliberately different when you go through scan:

• External rule packs are not kind-locked. --rule org/repo on scan runs every rule kind the pack ships; on a specialized command only that command’s kind runs.
• .gitignore handling for manifests. The specialized containers and iac commands prune gitignored manifests; scan, sca, sast and secrets do not, because dependency manifests routinely live in gitignored install directories. --include-ignored overrides the SAST-family behaviour.

Replaying results is not a scan: use report (scan --from-memory is a deprecated alias for it).

Usage

vulnetix scan [flags]

Flags

Output Files

After every scan the following files are written under your project root:

Suppressing findings. To drop findings you have triaged (false positives, accepted risks, mitigated issues) use nosec comments in code or the vulnetix ignore command. Scans report how many findings each pass suppressed, so nothing disappears silently.

Package Scope Support

Vulnerabilities and packages are organised by dependency scope where the package manager provides that information:

Supported Manifest Files

The scanner recognizes these package manager manifest and lock files:

JavaScript / TypeScript

When package.json is present without package-lock.json, yarn.lock, or pnpm-lock.yaml, SCA resolves from the installed node_modules/ tree. The scan fails before the VDB lookup if node_modules/ is missing or if any direct dependency declared in package.json is not installed. When the install tree is present, Vulnetix reads each installed package’s package.json, uses the actual installed versions in the /v2/cli.sca request, and adds installed undeclared packages as transitive dependencies where it can connect them through package manifest dependency fields.

Python

Conda

Nested pip: dependencies inside a Conda environment.yml are attributed to PyPI.

Go

Rust

Deno

Ruby

Java / Kotlin / Scala

Clojure

Clojure coordinates resolve as Maven group:artifact PURLs.

C# / .NET

PHP

Swift / iOS

Dart

Elixir

Erlang

C / C++

CMakeLists.txt is only recognized when the file contains CPMAddPackage.

Haskell

OCaml

Nix

Julia

Crystal

R

Zig

Bazel / Buck

Containers

Container images from FROM lines, Compose image: fields, Kubernetes manifests, and Helm charts are emitted as pkg:oci/… components. Each carries a vulnetix:oci:registryType (dockerhub/gcr/ecr/acr/ghcr/gitlab/quay/local/private) and vulnetix:oci:private property so private-registry usage is visible in the BOM.

Kubernetes

Container images are extracted from every pod-template shape — Pod, Deployment, ReplicaSet, StatefulSet, DaemonSet, Job and CronJob — including initContainers and ephemeralContainers.

Helm

Chart dependencies become pkg:helm/… components; container images declared in a sibling values.yaml (image: shorthand or repository:/tag: blocks) are emitted as pkg:oci/….

Registry config

These are not parsed for dependencies. The scanner extracts declared registry endpoints (never auth tokens) and prints an informational note when a private/custom registry is configured — a supply-chain visibility signal.

Infrastructure as Code

CI/CD

Existing SBOMs

The scanner also detects and ingests existing SBOM documents:

• SPDX JSON documents (identified by spdxVersion and SPDXID fields)
• CycloneDX JSON documents (identified by bomFormat: "CycloneDX" and specVersion)

License Analysis

By default, vulnetix scan also runs license analysis on all discovered packages. License findings appear in the pretty output after the vulnerability summary and are stored in the CycloneDX BOM with source vulnetix-license-analyzer.

License resolution uses a multi-source pipeline (manifests, filesystem, container metadata, deps.dev, GitHub). See the License Command Reference for full details on resolution sources, evaluation rules, and conflict detection.

To skip license analysis:

vulnetix scan --no-licenses

Feature Control

By default, vulnetix scan runs all analysis categories: SCA, SAST (including secret detection, container rules, and IaC rules), and license analysis.

Enabling individual features (exclusive mode)

When any --evaluate-X flag is set, only the explicitly enabled categories run — everything else is disabled. This makes it easy to scope a scan to a single concern:

# SCA only (vulnerability analysis on package manifests)
vulnetix scan --evaluate-sca

# SAST only (general static analysis rules)
vulnetix scan --evaluate-sast

# Secret detection only
vulnetix scan --evaluate-secrets

# Container analysis only (Dockerfile/OCI rules)
vulnetix scan --enable-containers

# IaC analysis only (Terraform, Nix)
vulnetix scan --evaluate-iac

# License analysis only
vulnetix scan --evaluate-licenses

Disabling individual features

--no-X flags disable a specific category while leaving all others enabled:

# Run everything except license analysis
vulnetix scan --no-licenses

# Run everything except secret-detection rules
vulnetix scan --no-secrets

# Skip IaC files and rules
vulnetix scan --no-iac

# Skip containers
vulnetix scan --no-containers

# Skip all SAST-kind rules (but still run secrets/containers/IaC rules)
vulnetix scan --no-sast

Specialized scan commands

For convenience, dedicated top-level commands wrap common single-category scans:

SAST (Static Application Security Testing)

By default, vulnetix scan also runs SAST analysis alongside SCA. SAST evaluates Rego-based rules against your source files to detect code-level security issues — weak cryptography, hardcoded credentials, missing lock files, insecure deserialization, and more.

SAST findings appear in the pretty output after the SCA summary and are written to .vulnetix/sast.sarif in SARIF 2.1.0 format. Each finding includes CWE, CAPEC, and MITRE ATT&CK technique mappings, plus stable fingerprints for tracking results across runs.

SAST rules are organized into four sub-categories that can be toggled independently:

Disabling SAST

# Skip all SAST-kind rules (secrets/containers/IaC still run)
vulnetix scan --no-sast

# Skip secret-detection rules specifically
vulnetix scan --no-secrets

# Skip all SAST entirely (all four sub-categories)
vulnetix scan --no-sast --no-secrets --no-containers --no-iac

# Skip built-in rules only (external rule repos still loaded)
vulnetix scan --disable-default-rules --rule myorg/my-rules

Listing Built-in Rules

Prints all all built-in rules with their IDs, names, severities, and language targets, then exit:

vulnetix scan --list-default-rules

External Rule Repos

Load additional Rego rules from Git repositories. See the Custom Rule Repositories guide for a full walkthrough including repository setup, rule authoring, and all flag combinations. Rules are fetched from GitHub by default or from a custom registry.

# Load rules from a GitHub repo
vulnetix scan --rule myorg/custom-rules

# Load multiple external rule repos
vulnetix scan --rule myorg/rules-a --rule myorg/rules-b

# Use a custom registry (e.g. GitLab or self-hosted Gitea)
vulnetix scan --rule myorg/rules --rule-registry https://gitlab.example.com

SAST Severity Gating

SAST findings participate in --severity gating alongside SCA vulnerabilities. When any SAST finding meets or exceeds the threshold, the scan exits with code 1:

# Exit 1 on high or critical SAST findings (or SCA vulnerabilities)
vulnetix scan --severity high

Built-in Rules

27 rules ship with the CLI. Run vulnetix scan --list-default-rules for full descriptions and CWE/CAPEC/ATT&CK mappings.

Cryptography

Container Security

Go

Java

Node.js

PHP

Python

Ruby

Rust

Secrets & Credentials

SARIF Output

SAST results are always written to .vulnetix/sast.sarif. To write a combined SARIF report (SCA + SAST) to a custom path, use --output:

# Write combined SARIF to a file; pretty summary still goes to stdout
vulnetix scan --output results.sarif

# Write both CycloneDX and SARIF files alongside pretty output
vulnetix scan --output sbom.cdx.json --output results.sarif

The auto-written .vulnetix/sast.sarif contains SAST-only findings. The --output *.sarif file contains all scan findings (SCA + SAST) in SARIF format.

Auto-Discovery

The scanner walks the directory tree starting from --path up to --depth levels deep. It automatically skips common non-project directories:

• node_modules, .git, .hg
• __pycache__, .tox, .venv
• vendor, .cargo

Use --exclude to skip additional paths by glob pattern.

Dependency graph from installed packages

After parsing manifests, the scanner also reads locally installed package directories to build a complete transitive dependency graph. This improves SBOM dependencies section accuracy and powers --paths output — no extra flags required.

If the install directory is not present, the scanner falls back to lock-file edge parsing where available.

For npm projects without a lock file, the installed node_modules/ tree is not just an edge source: it is the authoritative source for resolved package versions. Orphaned installed packages are tolerated as best-effort transitives, but missing direct dependencies stop the scan early because the CLI cannot safely infer what version should be reported.

Examples

Auto-discover and scan the current directory

vulnetix scan

Scan a specific project directory

vulnetix scan --path /path/to/project --depth 5

Exclude test fixtures and vendor directories

vulnetix scan --exclude "test/**" --exclude "vendor/**"

Emit CycloneDX JSON to stdout

vulnetix scan --output json-cyclonedx

Emit SARIF JSON to stdout

vulnetix scan --output json-sarif

Write CycloneDX to a file (pretty output still goes to stdout)

vulnetix scan --output /tmp/sbom.cdx.json

Write SARIF to a file (pretty output still goes to stdout)

vulnetix scan --output /tmp/results.sarif

Write both CycloneDX and SARIF files alongside pretty output

vulnetix scan --output /tmp/sbom.cdx.json --output /tmp/results.sarif

Raw CycloneDX JSON for scripting

vulnetix scan -o json-cyclonedx | jq '.components'

Suppress progress indicators (useful in CI without a TTY)

vulnetix scan --no-progress

Break the build on high or critical vulnerabilities

# Exit 1 if any high or critical vulnerability is found
vulnetix scan --severity high

# Exit 1 on any scored severity and write a CycloneDX BOM
vulnetix scan --severity low -o dist/sbom.cdx.json

Gate on EOL runtimes and packages

# Exit 1 when a runtime or package dependency is end-of-life
vulnetix scan --block-eol

# Combine with severity gating
vulnetix scan --block-eol --severity high

Gate on version lag (supply chain freshness)

# Exit 1 if using the very latest published version of any dependency
vulnetix scan --version-lag 1

# Exit 1 if any dependency is within the 3 most recent releases
vulnetix scan --version-lag 3

Gate on recently published dependencies (cooldown period)

# Exit 1 if any dependency was published in the last 3 days
vulnetix scan --cooldown 3

# Combine multiple supply chain gates
vulnetix scan --block-malware --block-unpinned --version-lag 1 --cooldown 3 --severity high

Suppress output when clean (results-only mode)

# No output when scan is clean; table appears only when findings exist
vulnetix scan --results-only

SAST — list, disable, and load custom rules

# List all built-in SAST rules and exit
vulnetix scan --list-default-rules

# Skip all SAST-kind rules (general static analysis)
vulnetix scan --no-sast

# Skip secret detection
vulnetix scan --no-secrets

# Skip all SAST entirely (all four sub-categories)
vulnetix scan --no-sast --no-secrets --no-containers --no-iac

# Skip built-in rules but load a custom rule repo from GitHub
vulnetix scan --disable-default-rules --rule myorg/custom-rules

# Load additional rules on top of the built-in set
vulnetix scan --rule myorg/extra-rules

# Use a self-hosted registry for custom rules
vulnetix scan --rule myorg/rules --rule-registry https://git.example.com

Suppress extra sections

# Skip exploit intelligence and remediation details
vulnetix scan --no-exploits --no-remediation

Skip license analysis

vulnetix scan --no-licenses

Dry run (detect files, no API calls)

vulnetix scan --dry-run

Reconstruct results from previous scan

# From memory — no API calls
vulnetix scan --from-memory

# Replaying stored results — prefer `vulnetix report`
vulnetix report --fresh-exploits
vulnetix report --fresh-advisories

# The deprecated equivalents (still accepted)
vulnetix scan --from-memory --fresh-exploits
vulnetix scan --from-memory --fresh-advisories

Org Quality Gate Policy

When you run a scan while authenticated and your organization has configured a Quality Gate, its settings are pulled in before the gate is evaluated and override the matching scan flag defaults — org policy always wins, even over a flag you pass explicitly. The override applies to --severity, --block-eol, --block-malware, --block-unpinned, --exploits, --version-lag, --cooldown, --sca-autofix-strategy, and --sca-autofix-max-major-bump. Settings the org left unset fall back to your flag or the builtin default.

Run with --verbose to see which settings were applied or superseded. Inspect the active policy with:

vulnetix config get quality-gate

Non-authenticated scans (no credentials, or the community fallback) have no organization to read from and use only the CLI flags you pass.

Exit Codes