pbom

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
• type ContainerImage
• type CycloneDX
• type CycloneDXComponent
• type CycloneDXMetadata
• type CycloneDXProperty
• type CycloneDXTool
• type Generator
  • func NewGenerator(projectPath string, projectID int, gitlabURL, branch string) *Generator
  • func (g *Generator) Generate(imageData *collector.GitlabPipelineImageData, ...) *PBOM
  • func (g *Generator) WithComplianceData(data *ImageComplianceData) *Generator
  • func (g *Generator) WithIncludeOverrideData(data *IncludeOverrideData) *Generator
• type ImageComplianceData
• type Include
• type IncludeOverrideData
• type PBOM
  • func (p *PBOM) ToCycloneDX(plumberVersion string) *CycloneDX
• type PlumberScoreCounts
• type PlumberScoreSummary
• type ProjectInfo
• type Summary

Constants

const CycloneDXSpecVersion = "1.5"

CycloneDX spec version we're generating

const Version = "1.0.0"

Version is the current PBOM specification version

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"`
	SerialNumber string               `json:"serialNumber"`
	Version      int                  `json:"version"`
	Metadata     CycloneDXMetadata    `json:"metadata"`
	Components   []CycloneDXComponent `json:"components"`
}

CycloneDX represents a CycloneDX SBOM Spec: https://cyclonedx.org/docs/1.5/json/

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 (*Generator) Generate

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

Generate creates a PBOM from pipeline data collections

func (*Generator) WithComplianceData

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

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

func (*Generator) WithIncludeOverrideData

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

WithIncludeOverrideData attaches override detection results so the PBOM marks overridden includes

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"
	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"`
}

Include represents an include/component/template used in the pipeline

type IncludeOverrideData

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 {
	// Metadata
	PBOMVersion string    `json:"pbomVersion"`
	GeneratedAt time.Time `json:"generatedAt"`

	// Project information
	Project ProjectInfo `json:"project"`

	// Pipeline dependencies
	ContainerImages []ContainerImage `json:"containerImages"`
	Includes        []Include        `json:"includes"`

	// Summary statistics
	Summary Summary `json:"summary"`

	// PlumberScore is optional letter Score (A–E) and numeric Points (0–100); set when analyze uses --score and/or --score-point.
	PlumberScore *PlumberScoreSummary `json:"plumberScore,omitempty"`
}

PBOM represents a Pipeline Bill of Materials - an inventory of all dependencies used in a CI/CD pipeline.

func (*PBOM) ToCycloneDX

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

ToCycloneDX converts a PBOM to CycloneDX format

type PlumberScoreCounts

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

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"`
	GitLabURL string `json:"gitlabUrl"`
	Branch    string `json:"branch,omitempty"`
}

ProjectInfo contains information about the analyzed project

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"`
}

Summary provides aggregate statistics about the pipeline dependencies