BOMHort on BOMHort Documentation

Overview

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

The Go client for the BOMHort REST API.

Complete: every public endpoint of the BOMHort api-gateway — SBOMs, findings, dependency trees, licenses, VEX, projects, clusters, namespaces, fleet, statistics, search, push-model uploads and source attribution (coverage).
Zero dependencies: standard library only.
Production behaviour built in: API key / service token auth, client-side rate limiting, 429 retries honouring Retry-After, typed errors, iterator-based pagination, streaming downloads.
Testable: bomhorttest is an in-memory fake gateway with BOMHort’s real upload, VEX scoping and matching semantics.
Verified against real BOMHort: every PR runs the integration suite with strict decoding against the pinned BOMHort release; a weekly job also runs it against BOMHort main to catch API drift.
Versioned with BOMHort: bomhort-go v0.8.x is the client for BOMHort 0.8.x (compatibility).

Extracted from VEXViper’s internal/bomhort (why).

Overview

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

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.

Testing

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

Quick Start

# Run all tests
cd backend && go test ./... -count=1

# Run with verbose output
go test ./... -v -count=1

# Run tests for a specific package
go test ./internal/vex/ -v -count=1

# Run a single test by name
go test ./internal/vex/ -run TestNormalizeVulnID -v

# Run with race detection (used in CI)
go test ./... -count=1 -race

# Check coverage
go test ./... -coverprofile=coverage.out
go tool cover -html=coverage.out

Test Structure

Tests live next to the code they test, using Go’s _test.go convention:

Why we renamed SeeBOM to BOMHort

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

What changed

The project name is now BOMHort (formerly known as SeeBOM).

The rename only affects branding and repository naming. The mission and technical direction stay the same: Kubernetes-native SBOM ingestion, enrichment, visualization, and governance.

Why we renamed

The name SeeBOM served us well, but it created confusion: spoken out loud, it sounds very similar to CBOM (Cryptography Bill of Materials).

In the xBOM ecosystem, names like CBOM usually refer to BOM document types, not to tools. Ahead of OpenSSF sandbox intake, we wanted a project name that is clearly identifiable as a platform.

Contributor Ladder

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

Overview

BOMHort uses a transparent contributor ladder inspired by the CNCF contributor ladder template. Each rung provides clear expectations and privileges, so you always know what the next step looks like.

┌─────────────────────────────────────────────┐
│ Maintainer — merge, release, direction │
├─────────────────────────────────────────────┤
│ Reviewer — approve PRs in their area │
├─────────────────────────────────────────────┤
│ Contributor — regular code/docs/tests │
├─────────────────────────────────────────────┤
│ Community — issues, discussions, usage │
└─────────────────────────────────────────────┘

🌱 Community Member

Who: Anyone who uses BOMHort, files issues, or participates in discussions.

SBOM Parsers

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

Overview

BOMHort supports multiple SBOM formats through a format-detection dispatch layer at internal/sbom/parse.go. When a file is processed, the dispatcher:

Reads the raw bytes
Probes JSON fields to identify the format
Routes to the appropriate parser backend
Returns a unified ParseResult (SBOM metadata + packages)

This happens transparently — the parsing worker simply calls sbom.Parse(reader, sourceFile, hash).

Supported Formats

Format	File Extension	Detection Method
SPDX 2.3 JSON	`.spdx.json`, `.json`	`"spdxVersion"` field present
In-toto attestation (SPDX)	`.spdx.json`, `.json`	`"predicateType"` contains “spdx”
CycloneDX 1.0–1.7 JSON	`.cdx.json`, `.json`	`"bomFormat": "CycloneDX"`

Parser Backends

Built-in (Default)

The default parsers use goccy/go-json for high-performance streaming and add zero additional dependencies beyond what BOMHort already requires.

AI Usage Policy

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

Policy

BOMHort welcomes AI-assisted contributions. We use AI tools extensively in our own development workflow (see AGENTS.md). However, we have clear rules to ensure accountability and code quality.

Rules

1. You own it

If you use AI to generate code, you are responsible for that code. Review it, test it, and understand it before submitting. “The AI wrote it” is not an excuse for bugs, security issues, or convention violations.

2. Sign your commits

Every commit must carry your DCO sign-off (Signed-off-by: Your Name <your@email.com>). This is non-negotiable — it certifies that you are the author and take responsibility, regardless of whether AI assisted you.

How to: Upload VEX

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

This is the contract between a VEX producer and BOMHort ≥ 0.7.0, as implemented in BOMHort’s parser (internal/vex/parser.go), parsing worker (cmd/parsing-worker/vex_scope.go, vex_rescue.go) and queries (internal/clickhouse). The E2E suite verifies each rule below against a real BOMHort, and bomhorttest implements the same rules.

1. Every statement belongs to exactly one SBOM

BOMHort has no fleet-wide VEX. A statement only ever affects findings of the SBOM it is scoped to:

Integration with BOMHort

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

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: Migrate from VEXViper's client

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

bomhort-go started as VEXViper’s internal/bomhort package and its bomhorttest fake. It keeps the same shape (functional options, APIError, UploadVEX(ctx, filename, doc, sbomID), sliding-window RateLimiter), but extends it to the full BOMHort API, which required a few breaking changes.

Imports

-import "github.com/seebom-labs/vexviper/internal/bomhort"
-import "github.com/seebom-labs/vexviper/internal/bomhort/bomhorttest"
+import bomhort "github.com/seebom-labs/bomhort-go"
+import "github.com/seebom-labs/bomhort-go/bomhorttest"

Client

VEXViper	bomhort-go	Notes
`ListSBOMs(ctx, page, pageSize, search)`	`ListSBOMs(ctx, &bomhort.SBOMListOptions{ListOptions: bomhort.ListOptions{Page: page, PageSize: pageSize}, Search: search})`	options struct; `nil` = server defaults
`AllSBOMs(ctx)`	`AllSBOMs(ctx, nil)`	or iterate lazily with `SBOMs(ctx, nil)`
`VEXStatements(ctx, page, pageSize)` (one page)	`ListVEXStatements(ctx, &bomhort.ListOptions{Page: page, PageSize: pageSize})`	`VEXStatements` is now the iterator
`AllVEXStatements(ctx)`	unchanged
`FindSBOM(ctx, ref)`	unchanged	now also matches uploaded filenames (`pushed/<uuid>-<name>`) and uses `?search=` first
`Vulnerabilities(ctx, id)`	`Vulnerabilities(ctx, id, nil)`	`&bomhort.VulnerabilityOptions{Scope: bomhort.ScopeDirect}` filters by dependency scope (BOMHort ≥ 0.8)
`Healthy`, `Dependencies`, `DownloadSBOM`, `UploadVEX`, `BaseURL`	unchanged
`WithAPIKey`, `WithServiceToken`, `WithHTTPClient`, `WithRateLimit`, `WithMaxRetries`	unchanged	new: `WithRateLimiter`, `WithUserAgent`, `WithStrictDecoding`
`IsNotFound(err)`	unchanged	new: `IsBadRequest`, `IsUnauthorized`, `IsForbidden`, `IsRateLimited`, `IsUnavailable`, `StatusCode`

Behaviour changes:

Testing

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

bomhort-go is tested at four levels. The first three run without network access or Docker.

Level	Where	Command	Runs in CI
Unit / wire contract	`*_test.go` in the root package	`make test-race`	every push/PR (`ci.yml`)
Fake gateway	`bomhorttest/server_test.go`	`make test-race`	every push/PR
Examples	`example_test.go` (`// Output:` checked)	`make test`	every push/PR
Integration / E2E	`test/integration` (`-tags integration`)	`make test-integration` / `make e2e`	every push/PR against the pinned BOMHort, weekly also against BOMHort `main` (`e2e.yml`)

Unit tests

endpoints_test.go is a table with one row per endpoint. Each row asserts method, escaped path, query string, headers, request body and the decoded response. Add a row for every new method.
client_test.go covers auth headers, retries on 429 (Retry-After and back-off; the sleep function is injected), context cancellation, error decoding and strict decoding.
misc_test.go covers upload validation, pagination helpers, FindSBOM and streaming downloads; ratelimit_test.go covers the limiter.

make cover enforces a minimum total coverage (COVER_MIN, default 85 %).

API Coverage

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

Every route of the BOMHort api-gateway (backend/cmd/api-gateway/main.go) and the client method that calls it.

Since is the first BOMHort release with the route (≤ 0.6 = present in 0.6.1, the oldest release checked). Routes newer than the server answer 404 (IsNotFound); newer query parameters are ignored and newer fields stay empty (COMPATIBILITY.md). Pagination column: ✓ = ListX page call + X iterator (+ AllX where useful).

How to: run VEXViper as a CronJob

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

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.

Compatibility & Versioning

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

Versions follow BOMHort

bomhort-go is released in lockstep with BOMHort: bomhort-go vX.Y.* is the client for BOMHort X.Y.*.

Major.minor is BOMHort’s. v0.8.0 ships when BOMHort 0.8.0 is final and covers its complete public API; a BOMHort minor without API changes still gets a (trivial) bomhort-go minor so the mapping stays obvious.
Patch is ours: client fixes, bomhorttest improvements, docs. v0.8.3 still targets BOMHort 0.8.x.
Pre-releases (v0.8.0-rc.N) track BOMHort release candidates when a consumer needs them early.
A newer client works against the previous BOMHort minor for everything that minor has (new routes answer 404 → IsNotFound, new fields are empty, new query parameters are ignored). An older client works against a newer BOMHort because decoding is lenient by default.

bomhort-go	Go	BOMHort	Tested in CI against
`v0.8.x`	1.25+ (`go.mod`) and latest stable	0.8.x	v0.8.0 (pinned, every PR) · `main` (weekly)

The pinned BOMHort ref lives in .github/workflows/e2e.yml (BOMHORT_PINNED_REF). Bump it — and this table — when a new BOMHort release (or RC) ships; see RELEASING.md.

How to: review VEX drafts in pull requests

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

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

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.