Go Client (bomhort-go) on BOMHort Documentation

Overview

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

Maintained in seebom-labs/bomhort-go — edit it there.

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).

How to: Upload VEX

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

Maintained in seebom-labs/bomhort-go — edit it there.

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:

How to: Migrate from VEXViper's client

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

Maintained in seebom-labs/bomhort-go — edit it there.

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

Maintained in seebom-labs/bomhort-go — edit it there.

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

Maintained in seebom-labs/bomhort-go — edit it there.

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).

Compatibility & Versioning

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

Maintained in seebom-labs/bomhort-go — edit it there.

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.