VEXViper on BOMHort Documentation

Overview

Mon, 01 Jan 0001 00:00:00 +0000

Maintained in seebom-labs/VEXViper — edit it there.

LLM-assisted OpenVEX generation for BOMHort.

BOMHort ingests SBOMs, matches them against OSV and applies OpenVEX statements — but it cannot produce VEX. Every CVE stays “effective” until somebody hand-writes an OpenVEX document. VEXViper closes that loop:

BOMHort findings ──► resolve product repo ──► clone + govulncheck + evidence
 ▲ │
 │ ▼
 └──── upload ◄── validated OpenVEX ◄── assessment (heuristic | OpenAI-compatible | MCP tool)

reads the vulnerability findings BOMHort already computed for an SBOM (vuln_id, purl, fixed_version, vex_status, …) — BOMHort is the single source of truth, VEXViper does not rescan anything;
resolves the product’s source repository (from the SBOM’s VCS metadata / PURLs, or --repo owner/name@ref), clones it shallowly and gathers deterministic evidence: installed vs fixed version, direct/transitive depth, govulncheck reachability for Go products, lockfile-graph / manifest / import evidence for npm, PyPI, Cargo, RubyGems, Composer, Maven, NuGet and Dart products (see Evidence per ecosystem), RustSec vulnerable-function references for Rust, Go symbol references, OSV details;
asks an assessment provider for status/justification/confidence/reasoning per finding — a rules-only heuristic (default, offline), any OpenAI-compatible endpoint, GitHub Models or the GitHub Copilot CLI (your Copilot subscription), or a tool on a configurable MCP server;
applies guardrails and emits an OpenVEX document built with openvex/go-vex whose every statement passes Statement.Validate() and reuses BOMHort’s (vuln_id, purl) verbatim so BOMHort’s exact-match join applies it;
optionally uploads it through POST /api/v1/sboms/upload and waits until BOMHort shows the new vex_status.

It is also an MCP server itself, so an LLM host (Claude Desktop, VS Code/Copilot, an agent) can drive or review the triage interactively.

Integration with BOMHort

Mon, 01 Jan 0001 00:00:00 +0000

Maintained in seebom-labs/VEXViper — edit it there.

This document records how VEXViper couples to BOMHort, which API contract it relies on, and what an upstream integration could look like.

1. Integration model

BOMHort (backend/, Go 1.25, stdlib HTTP, ClickHouse) exposes no plugin mechanism: no Go plugin loading, no gRPC/webhook hooks, no MCP. Its contribution guidelines require stdlib-only tests, discourage frameworks and ask contributors to ask first before adding Go dependencies. VEXViper needs openvex/go-vex, the MCP Go SDK, packageurl-go and yaml.v3 (plus the stdlib-only bomhort-go client), so the correct integration is an out-of-tree sidecar speaking the public REST API (docs/api-reference calls this “custom tooling”). Benefits:

How to: run VEXViper as a CronJob

Mon, 01 Jan 0001 00:00:00 +0000

Maintained in seebom-labs/VEXViper — edit it there.

Goal: VEXViper runs every few hours in your cluster, assesses every new BOMHort finding, uploads OpenVEX statements, and you can see them applied in BOMHort.

Prerequisites

A BOMHort ≥ 0.7 api-gateway reachable from the cluster with AUTH_ENABLED=true and an API key (or service token) that may upload.
helm 3 and kubectl against the target cluster.
The source repositories of your products reachable from the cluster (public GitHub works out of the box; private hosts need a token, see step 3).

Steps

Create the namespace and the secret. The chart reads api-key; github-token is optional and only needed for GitHub Models or private clones.

How to: review VEX drafts in pull requests

Mon, 01 Jan 0001 00:00:00 +0000

Maintained in seebom-labs/VEXViper — edit it there.

Goal: every VEX document VEXViper produces lands as a pull request in a git repository; a human reviews and merges it, and only merged statements are uploaded to BOMHort.

Prerequisites

A git repository for the statements, e.g. github.com/acme/vex-statements, with a base branch (main) that is protected so bots cannot merge.
A GitHub token with contents: write and pull_requests: write on that repository (fine-grained PAT or a GitHub App installation token). For GitHub Enterprise Server note the API URL (https://ghe.example.com/api/v3).
VEXViper installed (CLI or Helm, see How to: run VEXViper as a CronJob).

Steps

Configure the publishing target. CLI (vexviper.yaml):

How to: set up an LLM provider

Mon, 01 Jan 0001 00:00:00 +0000

Maintained in seebom-labs/VEXViper — edit it there.

Goal: VEXViper asks a language model for the verdict instead of using only the built-in rules, with a spend cap, and the model’s answer still passes the deterministic guardrails.

The provider only sees the evidence VEXViper collected (govulncheck result, dependency depth, lockfile graph, OSV data). A not_affected without strong evidence is always downgraded to under_investigation, whatever the model says.

Prerequisites

VEXViper working with provider: heuristic (see How to: run VEXViper as a CronJob).
One of:
- an OpenAI-compatible endpoint and key (OpenAI, Azure OpenAI, Ollama, vLLM, LiteLLM …);
- a GitHub account with a Copilot subscription — for GitHub Models a fine-grained PAT with the models: read permission (billed to the plan);
- the GitHub Copilot CLI installed and logged in on the machine that runs VEXViper (laptop or CI runner — the VEXViper container image does not ship it).

Steps

Pick one provider.