assembly

Documentation

Overview

Package assembly merges per-node CycloneDX BOMs into one consolidated SBOM.

The implementation is split by responsibility to keep the behavior traceable and maintainable: - assemble_flow.go: orchestration, dependency/composition assembly - normalize_scan.go: per-node scan normalization and local dedup - global_dedup.go: cross-node PURL deduplication - bomref.go: deterministic BOMRef planning and assignment - output.go: SBOM writing and file/CPE helpers

Index

• Constants
• func WriteSBOM(bom *cdx.BOM, path string, format string) error
• func WriteSBOMSPDX(bom *cdx.BOM, path string) error
• type SuppressionRecord
  • func Assemble(tree *extract.ExtractionNode, scans []scan.ScanResult, cfg config.Config) (*cdx.BOM, []SuppressionRecord, error)

Constants

const (
	// SuppressionFSArtifact identifies Syft file-cataloger entries that carry
	// an absolute temp-directory path as the component Name. These represent
	// the physical file record and are always superseded by a dedicated
	// package cataloger (e.g. java-archive-cataloger) when one is present.
	// When no package cataloger identifies the file, the entry is dropped to
	// prevent temp-path leakage and SBOM noise.
	SuppressionFSArtifact = "fs-cataloger-artifact"

	// SuppressionLowValueFile identifies type=file entries that carry no
	// PURL, version, or foundBy metadata. They convey no identification
	// value and cannot be matched to a vulnerability database.
	SuppressionLowValueFile = "low-value-file"

	// SuppressionWeakDuplicate identifies entries at the same
	// (delivery-path, evidence-path) locus whose quality score is lower than
	// the best entry in that group. Only dropped when the best entry is
	// clearly superior (score >= 4, i.e. has a PURL).
	SuppressionWeakDuplicate = "weak-duplicate"

	// SuppressionPURLDuplicate identifies entries that carry the same PURL as
	// another component and are therefore collapsed into a single surviving
	// representative. The survivor inherits all unique leaf-most delivery and
	// evidence paths from the whole group.
	SuppressionPURLDuplicate = "purl-duplicate"
)

Suppression reason constants used in SuppressionRecord.

Functions

func WriteSBOM

func WriteSBOM(bom *cdx.BOM, path string, format string) error

WriteSBOM persists a consolidated CycloneDX BOM as pretty-printed JSON or XML.

Why this exists: Assembly returns an in-memory BOM, while CLI and integration workflows need a stable on-disk artifact for scanners and audit workflows.

Typical use: Call WriteSBOM with the result from Assemble and the configured output path (usually "<output-dir>/<input>.cdx.json" or "<output-dir>/<input>.cdx.xml").

Parameters: - bom: CycloneDX BOM to encode - path: target file path to create or truncate - format: SBOM format string ("cyclonedx-json" or "cyclonedx-xml")

Returns an error when file creation fails or encoding cannot complete.

func WriteSBOMSPDX

func WriteSBOMSPDX(bom *cdx.BOM, path string) error

WriteSBOMSPDX converts the CycloneDX BOM to an SPDX 2.3 JSON document and writes it to path. If bom is nil or has no components, a minimal valid SPDX document is written.

Parameters: - bom: CycloneDX BOM to convert (may be nil) - path: target file path to create or truncate

Returns an error when file creation or encoding fails.

Types

type SuppressionRecord

type SuppressionRecord struct {
	// Reason is one of the Suppression* constants.
	Reason string
	// Component is the suppressed entry exactly as emitted by Syft.
	Component cdx.Component
	// FoundBy is the syft:package:foundBy value of the suppressed entry.
	FoundBy string
	// DeliveryPath is the delivery-path context at the time of suppression.
	DeliveryPath string
	// KeptName is the name of the component that replaced this one.
	// Only set for duplicate suppressions.
	KeptName string
	// KeptFoundBy is the foundBy of the replacement component.
	// Only set for duplicate suppressions.
	KeptFoundBy string
}

SuppressionRecord documents a component that was removed from the SBOM during normalization or deduplication. Every record that appears here must also appear in the audit report so that the suppression decision is traceable.

func Assemble

func Assemble(tree *extract.ExtractionNode, scans []scan.ScanResult, cfg config.Config) (*cdx.BOM, []SuppressionRecord, error)

Assemble builds one consolidated CycloneDX BOM from the extraction tree and per-node scan results.

Why this exists: The scan phase emits independent BOM fragments per extraction node, while downstream consumers need one auditable SBOM with deterministic references, containment dependencies, and completeness annotations.

Typical use: The orchestrator calls Assemble once after extraction and scanning. The returned BOM is written via WriteSBOM, and suppression records are passed to report generation for traceability.

Parameters: - tree: root extraction node that models the recursive delivery structure - scans: per-node scan results produced by scan.ScanAll - cfg: run configuration (root metadata, interpret mode, input path)

Returns: - *cdx.BOM: unified deterministic BOM - []SuppressionRecord: dropped/merged component records for audit reporting - error: assembly failures (for example, unrecoverable BOM construction issues)

Assumptions and constraints: - tree is expected to be non-nil and represent the processed input - component and dependency ordering is deterministic for reproducible output