Documentation
¶
Overview ¶
Package client is a thin HTTP client for the DevRadar SBOM ingest API.
Index ¶
- Constants
- type APIError
- type Attestation
- type Client
- func (c *Client) ArchiveSBOM(ctx context.Context, id string) error
- func (c *Client) Events(ctx context.Context, id string, opts ListOptions) (*EventsPage, error)
- func (c *Client) Failures(ctx context.Context, id string, limit int) ([]Failure, error)
- func (c *Client) Findings(ctx context.Context, id string, opts FindingsOptions) (*FindingsPage, error)
- func (c *Client) FleetLicenses(ctx context.Context) (*FleetLicenseStats, error)
- func (c *Client) GetSBOM(ctx context.Context, id, minSeverity string) (*SBOMDetail, error)
- func (c *Client) ImageSBOMs(ctx context.Context, repo string, opts ListOptions) (*ImageSBOMsPage, error)
- func (c *Client) Images(ctx context.Context, opts ImagesOptions) (*ImagesPage, error)
- func (c *Client) Licenses(ctx context.Context, id string) ([]PackageLicense, error)
- func (c *Client) ListVEX(ctx context.Context) ([]map[string]any, error)
- func (c *Client) Submit(ctx context.Context, in SubmitRequest) (*SubmitResponse, error)
- func (c *Client) SubmitVEX(ctx context.Context, doc []byte) (*VEXResult, error)
- func (c *Client) Timeline(ctx context.Context, repo string, opts ListOptions) (*TimelinePage, error)
- type Event
- type EventsPage
- type Failure
- type Finding
- type FindingsOptions
- type FindingsPage
- type FleetLicenseStats
- type Image
- type ImageSBOMsPage
- type ImagesOptions
- type ImagesPage
- type LicenseCount
- type ListOptions
- type PackageLicense
- type RepoImage
- type SBOMDetail
- type SeverityCounts
- type SubmitRequest
- type SubmitResponse
- type TimelineEvent
- type TimelinePage
- type VEXResult
Constants ¶
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.
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
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
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 ¶
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
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
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
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
Licenses returns the per-package license inventory for one SBOM, violations first.
func (*Client) ListVEX ¶ added in v0.3.0
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
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
LicenseCount is a keyed count in the fleet license rollup.
type ListOptions ¶ added in v0.3.0
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.