kief.dev

CLI Reference

Table of contents

vekt scan

Scan a directory for all supported lockfiles and check every package against the threat intel database.

vekt scan [PATH] [OPTIONS]

Arguments:

Argument Description Default
PATH Directory to scan . (current directory)

Options:

Flag Description
--json Output results as JSON instead of human-readable text
--malicious-only Report only confirmed malicious packages; suppress vulnerability findings
--quiet, -q Suppress all output when no findings are detected
--warn Report findings but exit 0 (for CI with known transitive vulns)

Behavior:

  • Walks the directory tree recursively
  • Skips node_modules, target, .venv, __pycache__, vendor, and .git directories
  • Skips hidden directories (names starting with .)
  • Deduplicates packages across multiple lockfiles before querying
  • Respects .vektignore rules (see below)
  • Prints findings to stdout; progress messages to stderr

Examples:

# Scan current directory
vekt scan .

# Scan a specific project
vekt scan /path/to/project

# JSON output for downstream processing
vekt scan . --json | jq '.[] | select(.findings | length > 0)'

# Only show malicious packages (fastest signal in CI)
vekt scan . --malicious-only

# Report findings but don't fail (for known transitive vulns)
vekt scan . --warn

# Silent on clean scan (for cron/scripts)
vekt scan . --quiet && echo "clean"

vekt check

Check a single lockfile against the threat intel database.

vekt check <LOCKFILE> [OPTIONS]

Arguments:

Argument Description
LOCKFILE Path to a lockfile

The lockfile type is inferred from the filename. The filename must exactly match a supported format (see supported lockfiles).

Options:

Flag Description
--json Output results as JSON
--malicious-only Report only confirmed malicious packages

Examples:

vekt check package-lock.json
vekt check /path/to/project/Cargo.lock
vekt check requirements.txt --json
vekt check Gemfile.lock --malicious-only

vekt list

List all supported lockfiles found in a directory without running any queries.

vekt list [PATH]

Arguments:

Argument Description Default
PATH Directory to search . (current directory)

Example:

vekt list .

Output groups lockfiles by ecosystem with counts.

vekt ci

CI/CD mode. Scans the current directory with severity-threshold gating and structured output formats including SARIF.

vekt ci [PATH] [OPTIONS]

Options:

Flag Description Default
--fail-on <LEVEL> Minimum severity to fail the build malicious
--format <FORMAT> Output format: text, json, sarif text
--malicious-only Report only confirmed malicious packages
--quiet Suppress output on clean scan

Severity levels for --fail-on:

Level Fails on
malicious Only confirmed malicious packages (MAL-*)
high Malicious + vulnerabilities with CVSS >= 7.0
medium Above + CVSS >= 4.0
low All findings

SARIF output conforms to SARIF v2.1.0 and can be uploaded to GitHub Advanced Security or any SARIF-compatible tool.

Examples:

# Fail only on malicious packages
vekt ci --fail-on malicious .

# Fail on high-severity and above, output SARIF
vekt ci --fail-on high --format sarif . > results.sarif

# JSON output for custom processing
vekt ci --format json .

See the CI/CD integration guide for full pipeline examples.

vekt audit

Check a package against the threat intel database before installing it. No lockfile needed.

vekt audit <SPEC> [OPTIONS]

Spec format: [ecosystem:]name[@version]

If no ecosystem prefix is given, defaults to npm. If no version is given, queries the registry for the latest version.

Ecosystem prefixes: npm, pypi, cargo, go, ruby, composer, nuget, pub, hex, hackage

Options:

Flag Description
--json Output results as JSON
--ecosystem <ECO> Override ecosystem detection

Examples:

# Check an npm package (default ecosystem)
vekt audit express@4.18.2

# Check a PyPI package
vekt audit pypi:requests@2.31.0

# Check a Rust crate
vekt audit cargo:serde@1.0.193

# Check latest version of a Go module
vekt audit go:golang.org/x/crypto

# JSON output
vekt audit npm:lodash@4.17.21 --json

vekt ignore

Manage the .vektignore file to suppress findings for known false positives or accepted risks.

vekt ignore add

Add a rule to .vektignore in the current directory.

vekt ignore add <ID> [OPTIONS]

Options:

Flag Description
--expires <DATE> Expiry date in YYYY-MM-DD format. Expired rules are not applied.
--package <ECO/NAME> Ignore all findings for a package (e.g., npm/lodash)

Examples:

# Ignore a specific vulnerability
vekt ignore add GHSA-jf85-cpcp-j695

# Ignore with an expiry (auto-unignore after date)
vekt ignore add CVE-2024-1234 --expires 2025-12-31

# Ignore all findings for a package
vekt ignore add --package npm/lodash

# Ignore a specific package version
vekt ignore add --package npm/lodash@4.17.21

# Wildcard patterns
vekt ignore add "CVE-2024-*"

vekt ignore list

Print all rules in the current .vektignore file with their status (active/expired).

vekt ignore list

vekt ignore remove

Remove a rule from .vektignore.

vekt ignore remove <ID>

vekt report

Planned. Generate a formatted security report from scan results.

vekt diff

Planned. Compare findings between two lockfile states (e.g., before and after a PR).

Exit codes

Code Meaning
0 Scan completed with no findings (or --warn flag used)
1 Scan completed and findings were detected above threshold
2 Scan error (parse failure, network error, invalid arguments)

Global options

Flag Description
(none) No global flags currently.

Environment variables

Variable Description
NO_COLOR Set to any value to disable ANSI color output

.vektignore file

The .vektignore file suppresses specific findings. Place it in the project root. Vekt walks up from the scan directory looking for it.

# Ignore a specific vulnerability by ID
GHSA-jf85-cpcp-j695

# Wildcard patterns
CVE-2024-*

# Ignore all findings for a package
pkg:npm/lodash

# Ignore a specific version
pkg:npm/lodash@4.17.21

# Time-limited ignore (expires automatically)
GHSA-xxxx-yyyy-zzzz expires:2025-12-31

# Comments start with #

Expired rules are automatically skipped. Use vekt ignore list to see active vs expired rules.