Quickstart

This guide gets you from zero to a working scan in under five minutes.

Table of contents

Install the CLI

Download a prebuilt binary

Prebuilt binaries for Linux, macOS, and Windows are available on the releases page.

Linux / macOS:

curl -fsSL https://kief.dev/vekt/install.sh | sh

This installs the vekt binary to ~/.local/bin. Make sure that directory is in your PATH.

Manual download:

# Linux x86_64
curl -Lo vekt https://kief.dev/vekt/releases/latest/vekt-linux-x86_64
chmod +x vekt
mv vekt ~/.local/bin/vekt

# macOS ARM64
curl -Lo vekt https://kief.dev/vekt/releases/latest/vekt-macos-arm64
chmod +x vekt
mv vekt /usr/local/bin/vekt

Build from source

Requires Rust 1.80 or later.

cargo install vekt

Verify the installation

vekt --version
# vekt 0.1.0

Run your first scan

Navigate to any project directory that has a lockfile and run:

vekt scan .

Vekt walks the directory tree, finds all supported lockfiles, and checks every package against the threat intel database.

Example output on a clean project:

Scanning 2 lockfiles in . ...
Querying threat intel for 312 unique packages ...

SCAN COMPLETE: 2 lockfiles | 312 packages | 0 findings
  No known vulnerabilities or malicious packages found.

Example output with findings:

Scanning 1 lockfiles in . ...

SCAN COMPLETE: 1 lockfiles | 847 packages | 3 findings

  CRITICAL: 1 MALICIOUS package(s) detected!
  WARNING: 2 known vulnerability(ies)

--> ./package-lock.json (package-lock.json)
    MALICIOUS MAL-2024-0123 [email protected] -- Steals npm tokens and sends to remote server
           https://osv.dev/vulnerability/MAL-2024-0123
    VULN GHSA-1234-5678-9012 [email protected] -- ReDoS vulnerability in semver parsing
           https://osv.dev/vulnerability/GHSA-1234-5678-9012
    VULN GHSA-9876-5432-1098 [email protected] -- Prototype pollution
           https://osv.dev/vulnerability/GHSA-9876-5432-1098

To check a single lockfile instead of scanning a directory:

vekt check package-lock.json
vekt check Cargo.lock
vekt check requirements.txt

Understand the output

Each finding has one of three labels:

MALICIOUS

The package has been confirmed as intentionally malicious. This typically means it contained code designed to steal credentials, exfiltrate data, execute remote commands, or backdoor the host system.

Action required: Remove the package immediately. Check your environment for signs of compromise. Do not run npm install or equivalent with this package present.

VULN

The package has a known security vulnerability -- a CVE, GHSA advisory, or equivalent. Vulnerabilities range in severity from critical to low. Each finding includes a link to the advisory for full details.

Action required: Review the advisory, assess exploitability in your context, and update to a patched version if available.

HOLDER

The package is a registry security-placeholder -- an inert stub published by the registry maintainers to occupy a name formerly used by a malicious package. The placeholder itself is not a threat, but its presence in your lockfile suggests a stale dependency that should be removed.

Action required: Remove the package from your dependencies. It provides no functionality.

Get an API key

The free tier allows 50 scans per day without an API key. For higher limits, sign up at kief.dev/vekt.

  1. Go to kief.dev/vekt
  2. Create an account or sign in
  3. Navigate to API Keys in your dashboard
  4. Click New Key, give it a name, and copy the key

Your API key looks like: vkt_live_xxxxxxxxxxxxxxxxxxxx

Configure the CLI

Set your API key so the CLI sends it with every request:

vekt auth set vkt_live_xxxxxxxxxxxxxxxxxxxx

The key is stored in ~/.config/vekt/config.toml. Verify it was saved:

vekt auth status
# Authenticated as: [email protected]
# Plan: Pro (5,000 scans/mo)
# Used this period: 42 scans

To remove the stored key:

vekt auth clear

You can also set the key via an environment variable without writing it to disk:

export VEKT_API_KEY=vkt_live_xxxxxxxxxxxxxxxxxxxx
vekt scan .

Set up CI/CD

Use vekt ci to fail your pipeline when high-severity findings are detected.

# Fail if any HIGH or CRITICAL findings are present
vekt ci --fail-on high

# Fail on any finding
vekt ci --fail-on low

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

Exit codes:

  • 0 -- no findings above the threshold
  • 1 -- findings detected above the threshold
  • 2 -- scan error (parse failure, network error, etc.)

GitHub Actions example

- name: Vekt supply chain scan
  run: vekt ci --fail-on high
  env:
    VEKT_API_KEY: ${{ secrets.VEKT_API_KEY }}

See the CI/CD integration guide for complete workflow examples.

Next steps