cdx

Documentation

Index

• func FormatSpec(specVersion string) string
• func NormalizeFormat(format string) (string, bool)
• func ValidSpecVersions() []string
• type Advisory
• type Affect
• type Analysis
• type BOM
  • func BuildFromLocalScan(results []LocalScanResult, specVersion string, scanCtx *ScanContext, seed *BOM) *BOM
  • func BuildFromScanTasks(tasks []*scan.ScanTask, specVersion string, scanCtx *ScanContext) *BOM
  • func (b *BOM) WriteJSON(w io.Writer) error
• type Component
• type ExternalReference
• type Lifecycle
• type LocalScanResult
• type Metadata
• type OrganizationalContact
• type Property
• type Rating
• type ScanContext
• type Source
• type Tools
• type Vulnerability

Functions

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 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"`
	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 (*BOM) WriteJSON

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

WriteJSON writes the BOM as indented JSON to the writer.

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"`
	// 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 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.