cdx

package
v3.12.0 Latest Latest
Warning

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

 Go to latest Published: Jun 1, 2026 License: AGPL-3.0 Imports: 10 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BuildLocalPurl added in v3.6.0 

func BuildLocalPurl(name, version, ecosystem string) string

buildLocalPurl builds a Package URL string for a dependency. BuildLocalPurl is the exported wrapper used by cmd/scan.go and internal/scan to derive the PURL the server-side /v2/cli.sca handler will use to key its vulnerability rows. Keep the result byte-identical with buildLocalPurl so both call sites produce the same purl string for the same package.

func ExportCompRefs 

func ExportCompRefs(bom *BOM) map[string]string

ExportCompRefs returns the component reference map built during BuildFromLocalScan. This is a helper to expose compRefs for dependency tree building without changing BuildFromLocalScan's signature.

func FormatSpec 

func FormatSpec(specVersion string) string

FormatSpec returns the format string for CLI display.

func NormalizeFormat 

func NormalizeFormat(format string) (string, bool)

NormalizeFormat maps user-facing format names to spec versions or output type. Returns (specVersion, isRawJSON).

func ParseUpstreamFromJSON added in v3.6.0 

func ParseUpstreamFromJSON(raw []byte) (map[string]any, error)

ParseUpstreamFromJSON decodes a JSON CycloneDX document into the untyped map shape that MergeUpstream consumes. Useful when the upstream data arrived as raw bytes (e.g. read from disk) rather than via the CLI client.

func PopulateLicenses 

func PopulateLicenses(bom *BOM, licenseMap map[string]string)

PopulateLicenses sets the Licenses field on BOM components using a license map. The map key is "name@version" → SPDX license ID or expression.

func ValidSpecVersions 

func ValidSpecVersions() []string

ValidSpecVersions returns the list of supported CycloneDX spec versions.

Types

type Advisory 

type Advisory struct {
	URL string `json:"url,omitempty"`
}

Advisory is an external advisory reference.

type Affect 

type Affect struct {
	Ref string `json:"ref"`
}

Affect identifies a component affected by a vulnerability.

type Analysis 

type Analysis struct {
	State         string `json:"state,omitempty"`
	Justification string `json:"justification,omitempty"`
	Detail        string `json:"detail,omitempty"`
}

Analysis contains vulnerability analysis state (CycloneDX VEX profile).

type BOM 

type BOM struct {
	BOMFormat       string          `json:"bomFormat"`
	SpecVersion     string          `json:"specVersion"`
	SerialNumber    string          `json:"serialNumber"`
	Version         int             `json:"version"`
	Metadata        *Metadata       `json:"metadata,omitempty"`
	Components      []Component     `json:"components,omitempty"`
	Dependencies    []CDXDependency `json:"dependencies,omitempty"`
	Vulnerabilities []Vulnerability `json:"vulnerabilities,omitempty"`
}

BOM is the top-level CycloneDX Bill of Materials.

func BuildFromLocalScan 

func BuildFromLocalScan(results []LocalScanResult, specVersion string, scanCtx *ScanContext, seed *BOM) *BOM

BuildFromLocalScan creates a CycloneDX BOM from locally-parsed manifest data and VDB findings.

Components are deduplicated by (name, version). Each component carries its ecosystem scope (required = production/runtime, optional = dev/test/peer/provided/system) and a PURL. Vulnerabilities include CVSS ratings and links back to affected components.

When scanCtx is non-nil the BOM metadata is enriched with git-repository context (branch, commit, dirty state, worktree, VCS remotes, recent authors) and host environment context (hostname, shell, OS, arch, user).

func BuildFromScanTasks 

func BuildFromScanTasks(tasks []*scan.ScanTask, specVersion string, scanCtx *ScanContext) *BOM

BuildFromScanTasks creates a CycloneDX BOM from completed scan tasks.

func MergeUpstream added in v3.6.0 

func MergeUpstream(local *BOM, upstream map[string]any) (*BOM, error)

MergeUpstream returns local mutated with upstream's vulns and component gap-fills applied. It is safe to pass nil for either side — a nil local is initialised as an empty BOM; a nil upstream is a no-op.

upstream is accepted as map[string]any because the API delivers an unmarshalled JSON object (not our local typed BOM struct) — see CliSCAResponse.CycloneDX in pkg/vdb/api_cli.go.

func (*BOM) WriteJSON 

func (b *BOM) WriteJSON(w io.Writer) error

WriteJSON writes the BOM as indented JSON to the writer.

type CDXDependency 

type CDXDependency struct {
	Ref       string   `json:"ref"`
	DependsOn []string `json:"dependsOn,omitempty"`
}

CDXDependency represents a CycloneDX dependency graph node.

func BuildDependencies 

func BuildDependencies(groups []scan.ManifestGroup, compRefs map[string]string) []CDXDependency

BuildDependencies creates the CycloneDX dependencies array from ManifestGroup edges. compRefs maps "name@version" → bom-ref for cross-referencing.

type Component 

type Component 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"`
	Scope       string `json:"scope,omitempty"`
	Purl        string `json:"purl,omitempty"`
	// Licenses is a CycloneDX 1.5+ licenseChoice array.
	Licenses []LicenseChoice `json:"licenses,omitempty"`
	// Authors is supported in CycloneDX 1.6+.
	Authors            []OrganizationalContact `json:"authors,omitempty"`
	ExternalReferences []ExternalReference     `json:"externalReferences,omitempty"`
	Properties         []Property              `json:"properties,omitempty"`
}

Component represents a software component.

type ExternalReference 

type ExternalReference struct {
	// Type is one of the CycloneDX defined types: vcs, website, issue-tracker,
	// distribution, license, build-meta, build-system, release-notes, other, etc.
	Type string `json:"type"`
	URL  string `json:"url"`
}

ExternalReference is an external URL resource associated with a component or the BOM.

type LicenseChoice 

type LicenseChoice struct {
	License    *LicenseData `json:"license,omitempty"`
	Expression string       `json:"expression,omitempty"`
}

LicenseChoice represents either a specific license or an SPDX expression.

type LicenseData 

type LicenseData struct {
	ID   string `json:"id,omitempty"`
	Name string `json:"name,omitempty"`
	URL  string `json:"url,omitempty"`
}

LicenseData describes a specific license.

type Lifecycle 

type Lifecycle struct {
	Phase       string `json:"phase,omitempty"`
	Name        string `json:"name,omitempty"`
	Description string `json:"description,omitempty"`
}

Lifecycle describes a phase in the product lifecycle (CycloneDX 1.5+). Use the Phase field for standard phases; set Name + Description for custom phases.

type LocalScanResult 

type LocalScanResult struct {
	File          scan.DetectedFile
	Packages      []scan.ScopedPackage
	Vulns         []scan.VulnFinding
	EnrichedVulns []scan.EnrichedVuln // populated after enrichment; used for full ratings
}

LocalScanResult holds the parsed packages and found vulnerabilities for one manifest file.

type Metadata 

type Metadata struct {
	Timestamp  string                  `json:"timestamp"`
	Lifecycles []Lifecycle             `json:"lifecycles,omitempty"`
	Tools      *Tools                  `json:"tools,omitempty"`
	Authors    []OrganizationalContact `json:"authors,omitempty"`
	// Component is the top-level subject described by this BOM.
	Component  *Component `json:"component,omitempty"`
	Properties []Property `json:"properties,omitempty"`
}

Metadata describes the BOM creation context (CycloneDX 1.5+).

type OrganizationalContact 

type OrganizationalContact struct {
	Name  string `json:"name,omitempty"`
	Email string `json:"email,omitempty"`
}

OrganizationalContact describes a person or organisation.

type Property 

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

Property is a name-value pair.

type Rating 

type Rating struct {
	Score    float64 `json:"score"`
	Severity string  `json:"severity,omitempty"`
	Method   string  `json:"method,omitempty"`
	Source   *Source `json:"source,omitempty"`
}

Rating is a vulnerability scoring entry.

type ScanContext 

type ScanContext struct {
	// Git is the git repository context collected from the scanned directory.
	Git *gitctx.GitContext
	// System is the host/process environment at scan time.
	System *gitctx.SystemInfo
	// ToolVersion is the version string injected at build time (e.g. "1.2.3").
	ToolVersion string
}

ScanContext carries optional environment-enrichment data passed to BOM builders. All fields are optional; nil pointers are silently ignored.

type Source 

type Source struct {
	Name string `json:"name,omitempty"`
	URL  string `json:"url,omitempty"`
}

Source identifies where vulnerability data comes from.

type Tools 

type Tools struct {
	Components []Component `json:"components,omitempty"`
}

Tools holds tool information in CycloneDX format.

type Vulnerability 

type Vulnerability struct {
	BOMRef      string     `json:"bom-ref,omitempty"`
	ID          string     `json:"id"`
	Source      *Source    `json:"source,omitempty"`
	Ratings     []Rating   `json:"ratings,omitempty"`
	Description string     `json:"description,omitempty"`
	Affects     []Affect   `json:"affects,omitempty"`
	Analysis    *Analysis  `json:"analysis,omitempty"`
	Properties  []Property `json:"properties,omitempty"`
	Advisories  []Advisory `json:"advisories,omitempty"`
}

Vulnerability represents a CycloneDX vulnerability entry.

Source Files

View all Source files

Directories

Path Synopsis
Package schema provides CycloneDX BOM validation against embedded JSON schemas.
 Package schema provides CycloneDX BOM validation against embedded JSON schemas.

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.