kief.dev

Quickstart

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

Table of contents

Install the CLI

One-line installer

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.

Windows (PowerShell):

irm https://kief.dev/vekt/install.ps1 | iex

This installs vekt.exe to %LOCALAPPDATA%\vekt and adds it to your user PATH.

Manual download

Prebuilt binaries are available for all platforms:

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

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

# macOS Intel
curl -Lo vekt https://kief.dev/vekt/releases/latest/vekt-darwin-x86_64
chmod +x vekt
mv vekt /usr/local/bin/vekt

# macOS Apple Silicon
curl -Lo vekt https://kief.dev/vekt/releases/latest/vekt-darwin-aarch64
chmod +x vekt
mv vekt /usr/local/bin/vekt

# Windows (PowerShell)
Invoke-WebRequest -Uri https://kief.dev/vekt/releases/latest/vekt-windows-x86_64.exe -OutFile vekt.exe

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 malicious-pkg@2.1.0 -- Steals npm tokens and sends to remote server
           https://osv.dev/vulnerability/MAL-2024-0123
    VULN GHSA-1234-5678-9012 semver@5.7.1 -- ReDoS vulnerability in semver parsing
           https://osv.dev/vulnerability/GHSA-1234-5678-9012
    VULN GHSA-9876-5432-1098 minimist@1.2.5 -- 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

An API key is required for all scans (CLI and API). The free tier is $0 with no credit card required.

  1. Go to kief.dev/vekt/signup
  2. Enter your email and select Free, Pro, or Team
  3. Your API key is shown once -- save it immediately

Your API key looks like: vkt_live_xxxxxxxxxxxxxxxxxxxx

If you lose your key, use the dashboard recovery flow to generate a new one via email.

Configure the CLI

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

export VEKT_API_KEY=vkt_live_xxxxxxxxxxxxxxxxxxxx
vekt scan .

To persist the key, add the export to your shell profile (~/.bashrc, ~/.zshrc, etc.):

echo 'export VEKT_API_KEY=vkt_live_xxxxxxxxxxxxxxxxxxxx' >> ~/.zshrc

On Windows, set it as a user environment variable:

[Environment]::SetEnvironmentVariable("VEKT_API_KEY", "vkt_live_xxxxxxxxxxxxxxxxxxxx", "User")

Set up CI/CD

Use vekt scan in your pipeline and let the exit code determine pass/fail.

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: Install Vekt
  run: curl -fsSL https://kief.dev/vekt/install.sh | sh

- name: Vekt supply chain scan
  run: ~/.local/bin/vekt scan . --quiet
  env:
    VEKT_API_KEY: ${{ secrets.VEKT_API_KEY }}

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

Next steps