Skip to content

Installation

Who this is for: anyone getting started with Vens. By the end of this page: you have Vens running — either as a CI step or as a local CLI binary.

GitHub Action

If you scan with Trivy or Grype in GitHub Actions, drop venslabs/vens-action into the workflow after the scan step:

- name: Scan image with Trivy
  run: trivy image python:3.11-slim --format json --output report.json

- name: Prioritize with vens
  uses: venslabs/vens-action@v0.2.0   # check the marketplace for the latest tag; pin by SHA in production
  with:
    version: v0.4.0                   # vens binary version
    config-file: .vens/config.yaml    # see ../guides/configuration.md to author this file
    input-report: report.json
    sbom-serial-number: ${{ vars.SBOM_SERIAL }}
    llm-provider: openai
    llm-model: gpt-4o
    llm-api-key: ${{ secrets.OPENAI_API_KEY }}
    fail-on-severity: critical        # break the build on critical OWASP risk

The action installs the binary, runs vens generate, and exposes severity counts as workflow outputs you can fail the build on. Full input/output reference, air-gapped runners, and the mock provider: see the GitHub Actions integration guide.

Run Vens locally

Vens ships as a single static binary. Pick the method that fits your workflow.

Prerequisites

Vens is not a scanner — it consumes reports produced by one. Before you start, make sure you have one of the following installed:

You will also need credentials for an LLM provider (OpenAI, Anthropic, Google AI or Ollama) — see Configure an LLM provider below.

go install github.com/venslabs/vens/cmd/vens@latest

Verify:

vens --version

Tip

Make sure $(go env GOPATH)/bin is in your $PATH.

Note

Pinning a specific version: go install github.com/venslabs/vens/cmd/vens@v0.3.0.

If you already use Trivy, install Vens as a native plugin — no separate binary to manage.

trivy plugin install github.com/venslabs/vens

Verify:

trivy vens --version

From now on, anywhere in this documentation where you see vens <command>, you can use trivy vens <command> instead.

Option 3 — Prebuilt binary

Download the latest release for your OS/architecture from the releases page, extract it, and put it in your $PATH.

# Replace VERSION with the actual tag, e.g. v0.3.0
curl -L https://github.com/venslabs/vens/releases/download/VERSION/vens_Linux_x86_64.tar.gz \
  | tar -xz
sudo mv vens /usr/local/bin/
vens --version

curl -L https://github.com/venslabs/vens/releases/download/VERSION/vens_Darwin_arm64.tar.gz \
  | tar -xz
sudo mv vens /usr/local/bin/
vens --version

curl -L https://github.com/venslabs/vens/releases/download/VERSION/vens_Darwin_x86_64.tar.gz \
  | tar -xz
sudo mv vens /usr/local/bin/
vens --version

Download vens_Windows_x86_64.zip from the releases page, extract it, and add the folder containing vens.exe to your PATH. Then in PowerShell:

vens --version

Note

Exact archive names follow the release assets. Check the releases page for the file matching your platform if unsure.

Verify the download

Release artifacts are signed with cosign in keyless mode: the signing identity is the GitHub Actions release workflow itself, certified by Sigstore — no long-lived key. Each release publishes SHA256SUMS and its Sigstore bundle SHA256SUMS.sigstore.json (signature, certificate, and transparency-log proof in one file). Download both alongside your archive from the releases page, then:

cosign verify-blob \
  --bundle SHA256SUMS.sigstore.json \
  --certificate-identity-regexp '^https://github.com/venslabs/vens/\.github/workflows/release\.yml@refs/tags/v' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  SHA256SUMS

sha256sum --check --ignore-missing SHA256SUMS

Note

Releases also carry a GitHub build-provenance attestation. Verify it with gh attestation verify <archive> --repo venslabs/vens.

Configure an LLM provider

Vens calls an LLM to score each CVE. All four providers below are first-class — pick whichever matches your constraints. Export credentials for one:

Vens asks the LLM to return structured JSON with four 0–9 component scores per CVE. If a model emits malformed JSON, you'll see unable to parse LLM output — see troubleshooting.

Run Ollama on the host where Vens runs (or another host on the same network), then pull a model:

ollama pull llama3.1:70b
# Lighter alternatives:
# ollama pull llama3.1:8b
# ollama pull mistral:7b

export OLLAMA_MODEL="llama3.1:70b"
# Optional — only set if Ollama runs on a different host than Vens:
export OLLAMA_HOST="http://ollama.internal:11434"

Nothing leaves the machine running Ollama — see Privacy and data flow.

export OPENAI_API_KEY="sk-..."
export OPENAI_MODEL="gpt-4o"

Among the cloud providers, only OpenAI currently accepts the seed parameter Vens forwards (--llm-seed); Anthropic and Google AI silently ignore it. This does not guarantee byte-identical scores across runs — see Reference: --llm-seed and Limitations.

export ANTHROPIC_API_KEY="sk-ant-..."
export ANTHROPIC_MODEL="claude-sonnet-4-5"

export GOOGLE_API_KEY="..."
export GOOGLE_MODEL="gemini-2.0-flash"

Auto-detection currently defaults to OpenAI. If you use a different provider, pass the --llm flag explicitly:

--llm openai      # default when auto
--llm anthropic
--llm googleai
--llm ollama

LLM cost

Cloud LLM pricing depends on model, prompt size, and CVE count. Vens does not estimate cost.

For an exact number, run once against your provider and read the billing dashboard. For a pre-run estimate, run with --debug-dir ./debug, count the tokens in debug/system.prompt, and plug into your provider's pricing page (the human.prompt file is overwritten on every batch and output tokens are not captured, so this is approximate).

For zero-cost or air-gapped runs, use Ollama.

Next step

Generate your first VEX: Quickstart (5 minutes).