client

package
v0.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 13, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package client is a thin HTTP client for the DevRadar SBOM ingest API.

Index

Constants

View Source
const (
	MaxSBOMBytes        = 20 << 20 // 20 MiB (POST /v1/sboms)
	MaxVEXBytes         = 5 << 20  // 5 MiB (POST /v1/vex)
	MaxAttestationBytes = 10 << 20 // 10 MiB — sigstore bundles are small; generous cap

)

Size caps mirror the DevRadar API's documented limits, enforced client-side so oversized inputs fail fast (before upload) and responses can't exhaust memory. MaxSBOMBytes / MaxVEXBytes are decoded-payload ceilings; the wire body is larger once base64-encoded, which the server also bounds.

View Source
const DefaultBaseURL = "https://devradar.thingz.io"

DefaultBaseURL is the public DevRadar service used when none is configured.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIError added in v0.3.1

type APIError struct {
	StatusCode int
	// Message is the server's human-readable error, or the trimmed raw body when
	// the response was not the {"error":"..."} envelope.
	Message string
	// contains filtered or unexported fields
}

APIError is a non-2xx response from the DevRadar API. It carries the HTTP status and the server's message (parsed from the standard {"error":"..."} envelope, falling back to the raw body), so callers can branch on the status (e.g. 429) instead of matching on strings.

func (*APIError) Error added in v0.3.1

func (e *APIError) Error() string

Error implements error. The message is already the server's text; the status is included so logs and unexpected cases stay diagnosable.

func (*APIError) TooManyRequests added in v0.3.1

func (e *APIError) TooManyRequests() bool

TooManyRequests reports whether the response was a 429 — either a rate limit or a tenant SBOM/image cap.

type Attestation added in v0.3.0

type Attestation struct {
	Result             string `json:"result,omitempty"`
	Mode               string `json:"mode,omitempty"`
	Binding            string `json:"binding,omitempty"`
	SubjectDigest      string `json:"subject_digest,omitempty"`
	PredicateType      string `json:"predicate_type,omitempty"`
	CertIdentity       string `json:"cert_identity,omitempty"`
	OIDCIssuer         string `json:"oidc_issuer,omitempty"`
	KeyID              string `json:"key_id,omitempty"`
	TransparencyLogRef string `json:"transparency_log_ref,omitempty"`
	VerifierVersion    string `json:"verifier_version,omitempty"`
	PolicyVersion      string `json:"policy_version,omitempty"`
	FailureReason      string `json:"failure_reason,omitempty"`
	VerifiedAt         string `json:"verified_at,omitempty"`
}

Attestation is the cryptographic verification evidence for an SBOM, present only when an attestation has been submitted and evaluated.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client submits SBOMs to a DevRadar service.

func New

func New(baseURL, token string) *Client

New returns a Client targeting baseURL (trailing slashes trimmed; falls back to DefaultBaseURL when empty) authenticating with the given bearer token.

func (*Client) ArchiveSBOM added in v0.3.0

func (c *Client) ArchiveSBOM(ctx context.Context, id string) error

ArchiveSBOM stops tracking an SBOM (idempotent; findings/history retained).

func (*Client) Events added in v0.3.0

func (c *Client) Events(ctx context.Context, id string, opts ListOptions) (*EventsPage, error)

Events returns the change log for one SBOM, newest first, keyset-paginated.

func (*Client) Failures added in v0.3.0

func (c *Client) Failures(ctx context.Context, id string, limit int) ([]Failure, error)

Failures returns recent scan failures for one SBOM, newest first.

func (*Client) Findings added in v0.3.0

func (c *Client) Findings(ctx context.Context, id string, opts FindingsOptions) (*FindingsPage, error)

Findings returns current findings for an SBOM at or above the requested severity floor, keyset-paginated.

func (*Client) FleetLicenses added in v0.3.0

func (c *Client) FleetLicenses(ctx context.Context) (*FleetLicenseStats, error)

FleetLicenses returns the tenant's fleet-wide license rollup.

func (*Client) GetSBOM added in v0.3.0

func (c *Client) GetSBOM(ctx context.Context, id, minSeverity string) (*SBOMDetail, error)

GetSBOM returns metadata and the severity breakdown for one SBOM. When minSeverity is non-empty it trims the breakdown.

func (*Client) ImageSBOMs added in v0.3.0

func (c *Client) ImageSBOMs(ctx context.Context, repo string, opts ListOptions) (*ImageSBOMsPage, error)

ImageSBOMs lists the submitted SBOMs (versions/digests) for a repository, newest generation first.

func (*Client) Images added in v0.3.0

func (c *Client) Images(ctx context.Context, opts ImagesOptions) (*ImagesPage, error)

Images lists the tenant's tracked images, grouped by repository and risk-ranked.

func (*Client) Licenses added in v0.3.0

func (c *Client) Licenses(ctx context.Context, id string) ([]PackageLicense, error)

Licenses returns the per-package license inventory for one SBOM, violations first.

func (*Client) ListVEX added in v0.3.0

func (c *Client) ListVEX(ctx context.Context) ([]map[string]any, error)

ListVEX returns the tenant's submitted OpenVEX documents (metadata only).

func (*Client) Submit

func (c *Client) Submit(ctx context.Context, in SubmitRequest) (*SubmitResponse, error)

Submit posts an SBOM to {baseURL}/v1/sboms and returns the decoded response. A non-2xx status is returned as an error including the response body.

func (*Client) SubmitVEX added in v0.3.0

func (c *Client) SubmitVEX(ctx context.Context, doc []byte) (*VEXResult, error)

SubmitVEX ingests a raw OpenVEX document (the caller supplies the JSON bytes).

func (*Client) Timeline added in v0.3.0

func (c *Client) Timeline(ctx context.Context, repo string, opts ListOptions) (*TimelinePage, error)

Timeline returns the change log for one repository across every version and digest, newest first.

type Event added in v0.3.0

type Event struct {
	Scanner    string  `json:"scanner"`
	EventType  string  `json:"event_type"`
	Exposure   string  `json:"exposure"`
	Package    string  `json:"package"`
	Severity   string  `json:"severity"`
	Score      float64 `json:"score"`
	Cause      string  `json:"cause"`
	OccurredAt string  `json:"occurred_at"`
}

Event is a single entry in an SBOM's change log.

type EventsPage added in v0.3.0

type EventsPage struct {
	Events []Event `json:"events"`
	// contains filtered or unexported fields
}

EventsPage is one page of an SBOM's change log.

type Failure added in v0.3.0

type Failure struct {
	Scanner    string `json:"scanner"`
	Stage      string `json:"stage"`
	Error      string `json:"error"`
	OccurredAt string `json:"occurred_at"`
}

Failure is a recent scan failure (a scanner errored or returned nothing).

type Finding added in v0.3.0

type Finding struct {
	Scanner   string  `json:"scanner"`
	Exposure  string  `json:"exposure"`
	Package   string  `json:"package"`
	Version   string  `json:"version"`
	Severity  string  `json:"severity"`
	Score     float64 `json:"score"`
	IsFixed   bool    `json:"is_fixed"`
	EPSS      float64 `json:"epss"`
	EPSSPct   float64 `json:"epss_pct"`
	KEV       bool    `json:"kev"`
	VEXStatus string  `json:"vex_status"`
}

Finding is a current vulnerability finding, with EPSS/KEV overlays joined when available.

type FindingsOptions added in v0.3.0

type FindingsOptions struct {
	ListOptions
	Fixable    bool
	Suppressed bool
}

FindingsOptions extends ListOptions with the findings-specific filters.

type FindingsPage added in v0.3.0

type FindingsPage struct {
	Findings []Finding `json:"findings"`
	// contains filtered or unexported fields
}

FindingsPage is one page of current findings.

type FleetLicenseStats added in v0.3.0

type FleetLicenseStats struct {
	Families   []LicenseCount `json:"families"`
	Categories []LicenseCount `json:"categories"`
	Packages   int            `json:"packages"`
	Unlicensed int            `json:"unlicensed"`
	Violations int            `json:"violations"`
}

FleetLicenseStats is the tenant's fleet-wide license landscape.

type Image added in v0.3.0

type Image struct {
	SBOMID      string         `json:"sbom_id"`
	ImageRef    string         `json:"image_ref"`
	Digest      string         `json:"digest"`
	Format      string         `json:"format"`
	SubmittedAt string         `json:"submitted_at"`
	Counts      SeverityCounts `json:"counts"`
	Failures    int            `json:"failures"`
}

Image is one submitted SBOM (version/digest) for a repository.

type ImageSBOMsPage added in v0.3.0

type ImageSBOMsPage struct {
	Repository string  `json:"repository"`
	SBOMs      []Image `json:"sboms"`
	// contains filtered or unexported fields
}

ImageSBOMsPage is one page of the SBOMs submitted for a repository.

type ImagesOptions added in v0.3.0

type ImagesOptions struct {
	ListOptions
	Query string // repository name substring (q)
	Label string
}

ImagesOptions extends ListOptions with the image-list filters.

type ImagesPage added in v0.3.0

type ImagesPage struct {
	Images []RepoImage `json:"images"`
	// contains filtered or unexported fields
}

ImagesPage is one page of tracked images.

type LicenseCount added in v0.3.0

type LicenseCount struct {
	Key   string `json:"key"`
	Count int    `json:"count"`
}

LicenseCount is a keyed count in the fleet license rollup.

type ListOptions added in v0.3.0

type ListOptions struct {
	MinSeverity string
	Sort        string
	Dir         string
	Cursor      string
	Limit       int
}

ListOptions carries the shared list query parameters. Zero-valued fields are omitted from the request, letting the service apply its defaults.

type PackageLicense added in v0.3.0

type PackageLicense struct {
	Package   string   `json:"package"`
	Version   string   `json:"version"`
	PURL      string   `json:"purl"`
	Licenses  []string `json:"licenses"`
	Category  string   `json:"category"`
	Violation bool     `json:"violation"`
	Reason    string   `json:"reason"`
}

PackageLicense is one package's licenses and the tenant policy verdict.

type RepoImage added in v0.3.0

type RepoImage struct {
	Repository  string         `json:"repository"`
	SBOMCount   int            `json:"sbom_count"`
	DigestCount int            `json:"digest_count"`
	Versions    []string       `json:"versions"`
	LatestAt    string         `json:"latest_at"`
	Counts      SeverityCounts `json:"counts"`
	Fixable     int            `json:"fixable"`
	Failures    int            `json:"failures"`
}

RepoImage is one tracked image, grouped by repository and risk-ranked.

type SBOMDetail added in v0.3.0

type SBOMDetail struct {
	SBOMID             string         `json:"sbom_id"`
	ImageRef           string         `json:"image_ref"`
	Digest             string         `json:"digest"`
	Format             string         `json:"format"`
	SpecVersion        string         `json:"spec_version"`
	Tool               string         `json:"tool"`
	ToolVersion        string         `json:"tool_version"`
	Status             string         `json:"status"`
	VerificationStatus string         `json:"verification_status"`
	SubmittedAt        string         `json:"submitted_at"`
	GeneratedAt        string         `json:"generated_at"`
	Counts             SeverityCounts `json:"counts"`
	Attestation        *Attestation   `json:"attestation,omitempty"`
}

SBOMDetail is the metadata and severity breakdown for one SBOM.

type SeverityCounts added in v0.3.0

type SeverityCounts struct {
	Critical   int `json:"critical"`
	High       int `json:"high"`
	Medium     int `json:"medium"`
	Low        int `json:"low"`
	Negligible int `json:"negligible"`
	Unknown    int `json:"unknown"`
	Total      int `json:"total"`
	Relevant   int `json:"relevant"`
}

SeverityCounts is a per-severity breakdown. Buckets below the requested threshold are omitted; unknown is always kept. Total is the overall count; Relevant sums the visible buckets.

type SubmitRequest

type SubmitRequest struct {
	// SBOM is the raw (un-encoded) SBOM document. It is base64-encoded on the wire.
	SBOM []byte
	// ImageRef is the digest-pinned image reference (repo@sha256:…), optional.
	ImageRef string
	// Version is the image tag (e.g. "v1.20.2"), optional.
	Version string
	// Labels are tenant grouping labels (e.g. "team-x", "prod"), optional.
	Labels []string
	// Attestation is the raw (un-encoded) sigstore/cosign bundle, optional. When
	// present it is base64-encoded on the wire; the service verifies it (if a
	// trust policy is configured) and reports the outcome in
	// SubmitResponse.VerificationStatus.
	Attestation []byte
}

SubmitRequest mirrors the POST /v1/sboms request body. Only SBOM is required; the rest override the service's own parsing of the SBOM when it is weak.

type SubmitResponse

type SubmitResponse struct {
	SBOMID   string `json:"sbom_id"`
	ImageRef string `json:"image_ref"`
	Digest   string `json:"digest"`
	Format   string `json:"format"`
	Existing bool   `json:"existing"`
	// VerificationStatus is the attestation outcome: unverified | verified | failed.
	VerificationStatus string `json:"verification_status"`
}

SubmitResponse mirrors the POST /v1/sboms response body.

type TimelineEvent added in v0.3.0

type TimelineEvent struct {
	Digest     string  `json:"digest"`
	SBOMID     string  `json:"sbom_id"`
	Scanner    string  `json:"scanner"`
	EventType  string  `json:"event_type"`
	Exposure   string  `json:"exposure"`
	Package    string  `json:"package"`
	Severity   string  `json:"severity"`
	Score      float64 `json:"score"`
	Cause      string  `json:"cause"`
	OccurredAt string  `json:"occurred_at"`
}

TimelineEvent is an Event across an image's digests, carrying the digest and sbom_id it occurred on.

type TimelinePage added in v0.3.0

type TimelinePage struct {
	Repository string          `json:"repository"`
	Timeline   []TimelineEvent `json:"timeline"`
	// contains filtered or unexported fields
}

TimelinePage is one page of an image's change history across digests.

type VEXResult added in v0.3.0

type VEXResult struct {
	DocumentID string `json:"document_id"`
	Statements int    `json:"statements"`
	Matched    int    `json:"matched"`
	Unmatched  int    `json:"unmatched"`
	Skipped    int    `json:"skipped"`
	Note       string `json:"note"`
}

VEXResult is the outcome of submitting an OpenVEX document.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL