pbom

package
v0.3.8 Latest Latest
Warning

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

 Go to latest Published: May 21, 2026 License: MPL-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package pbom provides Pipeline Bill of Materials (PBOM) generation.

A PBOM is an inventory of all dependencies used in a CI/CD pipeline, including container images and includes (components, templates, remote files). Unlike an SBOM (Software Bill of Materials) which tracks application dependencies, a PBOM tracks pipeline infrastructure dependencies.

Index

Constants

View Source 
const CycloneDXSpecVersion = "1.5"

CycloneDX spec version we're generating

View Source 
const Version = "1.0.0"

Version is the current PBOM specification version

Variables

This section is empty.

Functions

This section is empty.

Types

type ContainerImage 

type ContainerImage struct {
	// Full image reference (e.g., "docker.io/library/golang:1.22-alpine")
	Image string `json:"image"`

	// Parsed components
	Registry string `json:"registry"`
	Name     string `json:"name"`
	Tag      string `json:"tag,omitempty"`

	// Usage context
	Jobs []string `json:"jobs"`

	// Compliance status (from analysis, if available)
	Authorized   *bool `json:"authorized,omitempty"`
	ForbiddenTag *bool `json:"forbiddenTag,omitempty"`
}

ContainerImage represents a container image used in the pipeline

type CycloneDX 

type CycloneDX struct {
	BOMFormat    string               `json:"bomFormat"`
	SpecVersion  string               `json:"specVersion"`
	Version      int                  `json:"version"`
	SerialNumber string               `json:"serialNumber"`
	Metadata     CycloneDXMetadata    `json:"metadata"`
	Components   []CycloneDXComponent `json:"components"`
}

CycloneDX represents a CycloneDX SBOM Spec: https://cyclonedx.org/docs/1.5/json/ Struct field order matches a natural read path: BOM header, identifiers, metadata (project/tool), dependency components last.

type CycloneDXComponent 

type CycloneDXComponent struct {
	Type        string              `json:"type"`
	BOMRef      string              `json:"bom-ref,omitempty"`
	Name        string              `json:"name"`
	Version     string              `json:"version,omitempty"`
	Description string              `json:"description,omitempty"`
	Purl        string              `json:"purl,omitempty"`
	Properties  []CycloneDXProperty `json:"properties,omitempty"`
}

CycloneDXComponent represents a component in the BOM

type CycloneDXMetadata 

type CycloneDXMetadata struct {
	Timestamp  string              `json:"timestamp"`
	Tools      []CycloneDXTool     `json:"tools,omitempty"`
	Component  *CycloneDXComponent `json:"component,omitempty"`
	Properties []CycloneDXProperty `json:"properties,omitempty"`
}

CycloneDXMetadata contains metadata about the BOM

type CycloneDXProperty 

type CycloneDXProperty struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

CycloneDXProperty represents a name-value property

type CycloneDXTool 

type CycloneDXTool struct {
	Vendor  string `json:"vendor"`
	Name    string `json:"name"`
	Version string `json:"version"`
}

CycloneDXTool describes a tool used to create the BOM

type Generator 

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

Generator creates PBOMs from pipeline analysis data

func NewGenerator 

func NewGenerator(projectPath string, projectID int, gitlabURL, branch string) *Generator

NewGenerator creates a new PBOM generator

func NewGitHubGenerator added in v0.3.0 

func NewGitHubGenerator(projectPath, url, branch string) *Generator

NewGitHubGenerator creates a PBOM generator pre-configured for the GitHub provider. URL is the GitHub host (`github.com` or a GHES host); branch is informational, used to stamp the project section.

func (*Generator) Generate 

func (g *Generator) Generate(
	imageData *collector.GitlabPipelineImageData,
	originData *collector.GitlabPipelineOriginData,
) *PBOM

Generate creates a PBOM from pipeline data collections

func (*Generator) GenerateFromGitHubIR added in v0.3.0 

func (g *Generator) GenerateFromGitHubIR(pipeline *ir.NormalizedPipeline) *PBOM

GenerateFromGitHubIR builds a PBOM from the normalized GitHub pipeline IR. Container images are extracted from each job's `image:` and `services:` blocks; the GitHub analogue of GitLab's "include" list is the merged set of third-party action references (`uses: owner/repo@ref`) and reusable-workflow calls (`jobs.<name>.uses: …/.github/workflows/x.yml@ref`).

func (*Generator) WithComplianceData 

func (g *Generator) WithComplianceData(data *ImageComplianceData) *Generator

WithComplianceData attaches compliance results so the PBOM includes authorized/forbiddenTag fields

func (*Generator) WithGitHubComplianceData added in v0.3.0 

func (g *Generator) WithGitHubComplianceData(data *GitHubComplianceData) *Generator

WithGitHubComplianceData attaches per-image and per-action compliance lookups so the resulting PBOM marks each image with its authorized/forbiddenTag flags and each action with a custom property for unpinned status.

func (*Generator) WithIncludeOverrideData added in v0.1.47 

func (g *Generator) WithIncludeOverrideData(data *IncludeOverrideData) *Generator

WithIncludeOverrideData attaches override detection results so the PBOM marks overridden includes

type GitHubComplianceData added in v0.3.0 

type GitHubComplianceData struct {
	// ForbiddenTagImages keys on the full image reference
	// (`docker.io/golang:1.22`).
	ForbiddenTagImages map[string]bool
	// ImagesPinnedByDigest keys on the full image reference; true
	// when the image carries an `@sha256:…` suffix.
	ImagesPinnedByDigest map[string]bool
	// UnpinnedActions keys on the full action ref (`actions/checkout@v4`);
	// true when the ref is not a 40-char SHA.
	UnpinnedActions map[string]bool
	// ArchivedActions keys on the full action ref; true when the
	// upstream repository is archived (ISSUE-702). Sourced from the
	// per-action GitHub API metadata enrichment.
	ArchivedActions map[string]bool
	// VulnerableActions keys on the full action ref; true when the
	// upstream repository has at least one published GitHub Advisory
	// (ISSUE-703). Same metadata enrichment path as ArchivedActions.
	VulnerableActions map[string]bool
	// ActionAdvisories keys on the full action ref, value is the
	// list of GHSA IDs published against the action's repository.
	// Populated alongside VulnerableActions and surfaced into the
	// Include / CDX layer so consumers see which advisories triggered
	// the finding.
	ActionAdvisories map[string][]string
}

GitHubComplianceData carries the GitHub-side compliance lookups the PBOM enriches container images and actions with. Mirrors ImageComplianceData on the GitLab side; kept separate because the keys (action ref vs include path) and providers differ.

type ImageComplianceData 

type ImageComplianceData struct {
	// ForbiddenTagImages maps image links to true if they use a forbidden tag
	ForbiddenTagImages map[string]bool
	// UnauthorizedImages maps image links to true if they are from unauthorized sources
	UnauthorizedImages map[string]bool
}

ImageComplianceData holds compliance results for images to enrich PBOM output

type Include 

type Include struct {
	// Type of include: "component", "project", "local", "remote",
	// "template" (GitLab) or "action", "reusableWorkflow" (GitHub).
	Type string `json:"type"`

	// Location/path of the include
	Location string `json:"location"`

	// For project includes
	Project string `json:"project,omitempty"`

	// Version information
	Version       string `json:"version,omitempty"`
	LatestVersion string `json:"latestVersion,omitempty"`
	UpToDate      *bool  `json:"upToDate,omitempty"`

	// For components from GitLab CI/CD Catalog
	ComponentName string `json:"componentName,omitempty"`
	FromCatalog   bool   `json:"fromCatalog,omitempty"`

	// Whether this is a nested include (included by another include)
	Nested bool `json:"nested,omitempty"`

	// Override information (populated from control results)
	Overridden     bool                        `json:"overridden,omitempty"`
	OverriddenJobs []utils.OverriddenJobDetail `json:"overriddenJobs,omitempty"`

	// GitHub-only compliance enrichments populated from GitHubComplianceData.
	// Archived is true when the action's upstream repository is archived
	// (ISSUE-702). HasCVE is true when the action's upstream carries at
	// least one published GitHub Advisory (ISSUE-703). Advisories is the
	// list of GHSA IDs that triggered HasCVE.
	Archived   *bool    `json:"archived,omitempty"`
	HasCVE     *bool    `json:"hasCve,omitempty"`
	Advisories []string `json:"advisories,omitempty"`
}

Include represents an include/component/template used in the pipeline. On GitHub, the analogue of GitLab's "include" types are:

  • "action" — third-party `uses: owner/repo@ref` step
  • "reusableWorkflow" — `uses:` at the job level pointing at a reusable-workflow file

type IncludeOverrideData added in v0.1.47 

type IncludeOverrideData struct {
	// Overrides maps a clean include path to its overridden job details
	Overrides map[string][]utils.OverriddenJobDetail
}

IncludeOverrideData holds override detection results for includes. Key is the clean include location path (without version/instance prefix).

type PBOM 

type PBOM struct {
	PBOMVersion string    `json:"pbomVersion"`
	GeneratedAt time.Time `json:"generatedAt"`

	Project ProjectInfo `json:"project"`

	Summary Summary `json:"summary"`

	PlumberScore *PlumberScoreSummary `json:"plumberScore,omitempty"`

	ContainerImages []ContainerImage `json:"containerImages"`
	Includes        []Include        `json:"includes"`
}

PBOM represents a Pipeline Bill of Materials - an inventory of all dependencies used in a CI/CD pipeline. JSON field order follows encode/json struct order: version stamp, project context, aggregate summary, score, then inventories (read top-to-bottom).

func (*PBOM) ToCycloneDX 

func (p *PBOM) ToCycloneDX(plumberVersion string) *CycloneDX

ToCycloneDX converts a PBOM to CycloneDX format

type PlumberScoreCounts added in v0.1.83 

type PlumberScoreCounts struct {
	Critical int `json:"critical"`
	High     int `json:"high"`
	Medium   int `json:"medium"`
	Low      int `json:"low"`
}

PlumberScoreCounts is the number of issues per severity bucket.

type PlumberScoreSummary added in v0.1.83 

type PlumberScoreSummary struct {
	ProfileID            string             `json:"profileId"`
	RawPoints            float64            `json:"rawPoints"`
	FinalPoints          float64            `json:"finalPoints"`
	Score                string             `json:"score,omitempty"`
	CriticalMalusApplied bool               `json:"criticalMalusApplied,omitempty"`
	CriticalMalusMax     float64            `json:"criticalMalusMax,omitempty"`
	Counts               PlumberScoreCounts `json:"counts"`
}

PlumberScoreSummary mirrors control.PlumberScoreResult for JSON consumers (PBOM / SBOM).

type ProjectInfo 

type ProjectInfo struct {
	Path      string `json:"path"`
	ID        int    `json:"id,omitempty"`
	Provider  string `json:"provider,omitempty"`
	URL       string `json:"url,omitempty"`
	GitLabURL string `json:"gitlabUrl,omitempty"`
	Branch    string `json:"branch,omitempty"`
}

ProjectInfo contains information about the analyzed project. Provider names which CI platform produced this PBOM ("gitlab" or "github"). URL is the platform host used by the analysis (full URL on GitLab, host or host/api/v3 on GitHub). GitLabURL is kept for backward compatibility with v0.2.x consumers that key on it; new readers should prefer Provider + URL.

type Summary 

type Summary struct {
	// Image counts
	TotalImages      int `json:"totalImages"`
	UniqueRegistries int `json:"uniqueRegistries"`

	// Include counts
	TotalIncludes   int `json:"totalIncludes"`
	Components      int `json:"components"`
	ProjectIncludes int `json:"projectIncludes"`
	LocalIncludes   int `json:"localIncludes"`
	RemoteIncludes  int `json:"remoteIncludes"`
	Templates       int `json:"templates"`

	// GitHub-specific include counts. Always emitted (matches the
	// pattern the GitLab-side counters above use — zero is meaningful
	// and gets serialised as `0`, not dropped).
	Actions           int `json:"actions"`
	ReusableWorkflows int `json:"reusableWorkflows"`
}

Summary provides aggregate statistics about the pipeline dependencies

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.