normalize

package
v1.11.0 Latest Latest
Warning

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

 Go to latest Published: Jul 24, 2026 License: AGPL-3.0 Imports: 24 Imported by: 0

Documentation

Overview

Package normalize provides utilities for normalizing package identifiers. This file handles mapping binary package names to their source package names for Linux distributions (Debian, Alpine), enabling vulnerability matching against security advisories that reference source packages.

Index

Constants

View Source 
const GraphRootNodeID = "ROOT"

Variables

View Source 
var ErrNodeNotReachable = fmt.Errorf("node not reachable from current scope")
View Source 
var PURLEcosystems = map[string]string{
	"Alpine":    "apk",
	"crates.io": "cargo",
	"Debian":    "deb",
	"Go":        "golang",
	"Hackage":   "hackage",
	"Hex":       "hex",
	"Maven":     "maven",
	"npm":       "npm",
	"NuGet":     "nuget",
	"OSS-Fuzz":  "generic",
	"Packagist": "composer",
	"Pub":       "pub",
	"PyPI":      "pypi",
	"RubyGems":  "gem",
}

PURL conversion utilities

View Source 
var ValidSemverRegex = regexp.MustCompile(`^(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)(?:-(?P<prerelease>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?P<buildmetadata>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$`)

Regex for validating a correct semver.

Functions

func ArtifactPurl 

func ArtifactPurl(scanner string, assetName string) string

func AssetName added in v1.9.0 

func AssetName(assetName string) (string, error)

func AssetSlugPath added in v1.9.0 

func AssetSlugPath(assetName string) (string, error)

AssetSlugPath expands a normalized "<organization>/<project>/<asset>" name into the web UI path "<organization>/projects/<project>/assets/<asset>".

func BomIsSBOM 

func BomIsSBOM(bom *cdx.BOM) bool

func CheckVersion 

func CheckVersion(exactVersion, introduced, fixed *string, lookingForVersion, affectedComponentType string) (bool, error)

func ConvertToSemver 

func ConvertToSemver(originalVersion string) (string, error)

ConvertToSemver converts various version formats to semantic versioning format. It handles: - Epoch prefixes (e.g., "2:1.2.3" -> "1.2.3") - "v" prefixes (e.g., "v1.2.3" -> "1.2.3") - Pre-release identifiers with "-" (e.g., "1.2.3-rc1") - Build metadata with "+" (e.g., "1.2.3+build1") - Tilde versions "~" (e.g., "1.2.3~rc1" -> "1.2.3-rc1") - Missing version segments (e.g., "1.2" -> "1.2.0")

Returns an error if: - Version contains invalid characters (only 0-9 and . allowed in version part) - Version has more than 3 numeric segments

func CycloneDXVEXFromVulnerabilities added in v1.9.0 

func CycloneDXVEXFromVulnerabilities(vulns []cdx.Vulnerability, metadata BOMMetadata) *cdx.BOM

CycloneDXVEXFromVulnerabilities builds a CycloneDX VEX BOM directly from a set of vulnerabilities, without going through an SBOMGraph. The affected components (from each vulnerability's Affects refs) become the BOM's components, all declared as direct dependencies of the root component described by metadata.

func EncodeCanonical 

func EncodeCanonical(obj any) (out []byte, err error)

EncodeCanonical JSON canonicalizes the passed object and returns it as a byte slice. It uses the OLPC canonical JSON specification (see http://wiki.laptop.org/go/Canonical_JSON). If canonicalization fails the byte slice is nil and the second return value contains the error.

func FixFixedVersion 

func FixFixedVersion(purl string, fixedVersion *string) *string

func MergeCycloneDXVEX added in v1.9.0 

func MergeCycloneDXVEX(boms []*cdx.BOM, rootName string) *cdx.BOM

MergeCycloneDXVEX merges several CycloneDX VEX BOMs into one under a single release root. Because the components and dependencies are derived from the vulnerabilities' affected refs, merging is simply rebuilding the BOM from the union of all vulnerabilities.

func PURLToString 

func PURLToString(purl packageurl.PackageURL) (string, error)

func ParseGraphNodeID 

func ParseGraphNodeID(id string) (prefix, name string)

ParseGraphNodeID extracts the type prefix and name from a node ID. e.g., "artifact:my-app" -> ("artifact", "my-app")

func Purlify 

func Purlify(artifactName string, assetVersionName string) string

func SanitizeExternalReferencesURL 

func SanitizeExternalReferencesURL(url string) string

func SemverCompare 

func SemverCompare(v1, v2 string) int

func SemverSort 

func SemverSort(versions []string)

func SortStringsSlice 

func SortStringsSlice(slice []string) []string

func ToPurlWithoutVersion 

func ToPurlWithoutVersion(purl packageurl.PackageURL) string

func UppercaseCVEID 

func UppercaseCVEID(cveID string) string

Types

type BOMMetadata 

type BOMMetadata struct {
	AssetVersionSlug      string
	AssetSlug             string
	OrgSlug               string
	ProjectSlug           string
	FrontendURL           string
	ArtifactName          string
	AssetID               uuid.UUID
	AddExternalReferences bool
	RootName              string // defaults to ArtifactName if empty
	AssetVersionName      string
}

type FlatGraph 

type FlatGraph struct {
	Nodes []string
	Edges [][2]string
}

NodeIDsAndEdges returns a flat representation of the graph for comparison.

type GraphComponent 

type GraphComponent interface {
	GetID() string
	GetDependentID() string
	ToCdxComponent(componentLicenseOverwrites map[string]string) (cdx.Component, error)
}

GraphComponent represents a component that can be loaded from the database.

type GraphDiff 

type GraphDiff struct {
	AddedNodes   []*GraphNode // nodes added
	RemovedNodes []*GraphNode // nodes removed
	AddedEdges   [][2]string  // edges added [parent, child] - ROOT will be replaced by nil so that it matches the db schema
	RemovedEdges [][2]string  // edges removed [parent, child] - ROOT will be replaced by nil so that it matches the db schema
}

GraphDiff represents differences between two graph states.

func (GraphDiff) AddedNodeIDs 

func (d GraphDiff) AddedNodeIDs() []string

AddedNodeIDs returns just the IDs of added nodes.

func (GraphDiff) IsEmpty 

func (d GraphDiff) IsEmpty() bool

IsEmpty returns true if there are no changes.

func (GraphDiff) RemovedNodeIDs 

func (d GraphDiff) RemovedNodeIDs() []string

RemovedNodeIDs returns just the IDs of removed nodes.

type GraphNode 

type GraphNode struct {
	BOMRef string        // Unique identifier
	Type   GraphNodeType // What kind of node this is

	// For components, this holds the full CycloneDX component data
	Component *cdx.Component

	// InfoSource-specific fields (only set for GraphNodeTypeInfoSource)
	InfoType InfoSourceType
}

GraphNode represents any node in the SBOM graph. All nodes (root, artifacts, info sources, components) share this structure.

type GraphNodeType 

type GraphNodeType string

GraphNodeType identifies what kind of node this is in the graph. 

const (
	GraphNodeTypeRoot       GraphNodeType = "root"
	GraphNodeTypeArtifact   GraphNodeType = "artifact"
	GraphNodeTypeInfoSource GraphNodeType = "infosource"
	GraphNodeTypeComponent  GraphNodeType = "component"
)

type InfoSourceType 

type InfoSourceType string

InfoSourceType indicates where component information came from. 

const (
	InfoSourceSBOM InfoSourceType = "sbom"
)

func RemoveInformationSourcePrefixIfExists 

func RemoveInformationSourcePrefixIfExists(origin string) (InfoSourceType, string)

type Path 

type Path []string

Path represents a vulnerability path through the dependency graph. It can contain both structural nodes (root, artifact, info sources) and component nodes (PURLs).

func (Path) String 

func (p Path) String() string

String returns a comma-separated string of all nodes in the path.

func (Path) ToStringSlice 

func (p Path) ToStringSlice() []string

ToStringSlice returns all nodes in the path, including fake/structural nodes.

type PurlMatchContext 

type PurlMatchContext struct {
	SearchPurl                  string                    `json:"searchPurl"` // purl without version and qualifiers, used for database matching
	NormalizedVersion           string                    `json:"normalizedVersion"`
	HowToInterpretVersionString VersionInterpretationType `json:"howToInterpretVersionString"`
	Qualifiers                  packageurl.Qualifiers     `json:"qualifiers"`
	Namespace                   string                    `json:"namespace"`
}

PurlMatchContext holds the parsed purl information for matching

func ParsePurlForMatching 

func ParsePurlForMatching(purl packageurl.PackageURL) *PurlMatchContext

ParsePurlForMatching parses a purl and version into a context for database matching

type SBOMGraph 

type SBOMGraph struct {
	Nodes map[string]*GraphNode          // id -> node
	Edges map[string]map[string]struct{} // parent id -> set of child ids

	RootID string // ID of the root node (constant: "ROOT")

	ScopeID string // The id of the current scope node
}

SBOMGraph is a directed graph representing a software bill of materials.

Structure: 

ROOT
└── artifact:my-app
    └── sbom:package-lock.json
        └── pkg:npm/lodash@4.17.21
            └── pkg:npm/some-dep@1.0.0

All nodes live in the same graph. Scoping is done by traversing from a specific node.

func InvalidSBOMGraphFromCycloneDX added in v1.9.0 

func InvalidSBOMGraphFromCycloneDX(bom *cdx.BOM, artifactName, infoSourceID string) (*SBOMGraph, error)

InvalidSBOMGraphFromCycloneDX is like SBOMGraphFromCycloneDX but skips pruning unidentifiable components (e.g. a purl-less root). Call MakeValid once done enriching, or use SBOMGraphFromCycloneDX directly if you don't need to enrich the graph via EnrichSBOM first.

func NewSBOMGraph 

func NewSBOMGraph() *SBOMGraph

NewSBOMGraph creates an empty graph with a root node.

func SBOMGraphFromComponents 

func SBOMGraphFromComponents[T GraphComponent](components []T, licenseOverwrites map[string]string) (*SBOMGraph, error)

SBOMGraphFromComponents builds an SBOMGraph from database components. The components include artifact nodes, information source nodes, and regular components. This function reconstructs the full graph structure from the flat component list. Uses generics to avoid slice type conversion and reduce memory allocations.

func SBOMGraphFromCycloneDX 

func SBOMGraphFromCycloneDX(bom *cdx.BOM, artifactName, infoSourceID string) (*SBOMGraph, error)

SBOMGraphFromCycloneDX creates an SBOMGraph from a CycloneDX BOM. The original root component is always kept as a node in the graph when it has a valid PackageURL, so that re-uploading a downloaded SBOM is idempotent. When the root component has no (valid) PackageURL, it cannot be identified as a real package, so its direct dependencies are reparented to the info source node instead.

func (*SBOMGraph) AddArtifact 

func (g *SBOMGraph) AddArtifact(name string) string

AddArtifact adds an artifact node as a child of root.

func (*SBOMGraph) AddComponent 

func (g *SBOMGraph) AddComponent(comp cdx.Component) string

AddComponent adds a component node.

func (*SBOMGraph) AddEdge 

func (g *SBOMGraph) AddEdge(parentID, childID string)

AddEdge adds a directed edge from parent to child.

func (*SBOMGraph) AddInfoSource 

func (g *SBOMGraph) AddInfoSource(artifactID, sourceID string, sourceType InfoSourceType) string

AddInfoSource adds an information source node as a child of an artifact. The info source ID is unique per artifact to prevent conflicts when merging graphs.

func (*SBOMGraph) Artifacts 

func (g *SBOMGraph) Artifacts() iter.Seq[*GraphNode]

Artifacts returns all artifact nodes reachable from scope.

func (*SBOMGraph) Children 

func (g *SBOMGraph) Children(nodeID string) iter.Seq[*GraphNode]

Children returns an iterator over direct children of a node.

func (*SBOMGraph) ChildrenOfType 

func (g *SBOMGraph) ChildrenOfType(nodeID string, nodeType GraphNodeType) iter.Seq[*GraphNode]

ChildrenOfType returns children of a specific type.

func (*SBOMGraph) ClearScope 

func (g *SBOMGraph) ClearScope()

func (*SBOMGraph) Clone 

func (g *SBOMGraph) Clone() *SBOMGraph

Clone creates a deep copy of the graph.

func (*SBOMGraph) ComponentEdges 

func (g *SBOMGraph) ComponentEdges() iter.Seq2[string, string]

ComponentEdges returns edges between components only.

func (*SBOMGraph) Components 

func (g *SBOMGraph) Components() iter.Seq[*GraphNode]

Components returns all component nodes reachable from scope.

func (*SBOMGraph) ComponentsWithMultipleSources 

func (g *SBOMGraph) ComponentsWithMultipleSources() []string

ComponentsWithMultipleSources returns component IDs that appear in multiple SBOMs. These cannot be automatically marked as "fixed".

func (*SBOMGraph) CountInfoSourcesPerComponent 

func (g *SBOMGraph) CountInfoSourcesPerComponent() map[string]map[InfoSourceType]int

CountInfoSourcesPerComponent returns how many info sources each component appears under. Key insight: traverse from each info source and count how many times each component is reached.

func (*SBOMGraph) CurrentScopeID 

func (g *SBOMGraph) CurrentScopeID() string

func (*SBOMGraph) DeleteArtifactFromGraph 

func (g *SBOMGraph) DeleteArtifactFromGraph(artifactName string) GraphDiff

DeleteArtifactFromGraph removes an artifact and all its subtree from the graph. Returns a GraphDiff representing what was removed. DeleteArtifactFromGraph removes an artifact and all its subtree from the graph. Returns a GraphDiff representing what was removed. Only deletes nodes that are exclusively reachable through this artifact.

func (*SBOMGraph) EdgesIter added in v1.3.0 

func (g *SBOMGraph) EdgesIter() iter.Seq2[string, string]

EdgesIter returns all edges where both endpoints are reachable from scope.

func (*SBOMGraph) EnrichSBOM added in v1.9.0 

func (g *SBOMGraph) EnrichSBOM(extra *cdx.BOM, parentRef string) (isNew bool, err error)

EnrichSBOM adds or replaces extra's root component (and everything it declares) in g. If g already has a component with the same Name as extra's root (e.g. an unresolved binary a scan found but couldn't inspect further), that component's identity (BOMRef) is kept, but its whole subtree is replaced with extra's - down to no children at all, if that's what extra declares - via MergeGraph's existing "last source wins" replace semantics (including its automatic pruning of anything left unreachable). Otherwise extra's root is attached as a new child of parentRef, additively - parentRef keeps whatever other children it already had.

The returned bool reports which of those two happened: true if extra's root was attached as a brand new node, false if an existing component's subtree was replaced in place.

func (*SBOMGraph) FindAllComponentOnlyPathsToPURL 

func (g *SBOMGraph) FindAllComponentOnlyPathsToPURL(purl string, limit int) []Path

func (*SBOMGraph) GetArtifactIDs 

func (g *SBOMGraph) GetArtifactIDs() []string

GetArtifactIDs returns all artifact IDs in the graph.

func (*SBOMGraph) GetInfoSourceIDs 

func (g *SBOMGraph) GetInfoSourceIDs(artifactID string) []string

GetInfoSourceIDs returns all info source IDs for a given artifact.

func (*SBOMGraph) GetInfoSourceNode 

func (g *SBOMGraph) GetInfoSourceNode(infoSourceID string) *GraphNode

GetInfoSourceNode returns the info source node by ID, or nil if not found.

func (*SBOMGraph) GetParentIDs 

func (g *SBOMGraph) GetParentIDs(nodeID string) []string

GetParentIDs returns all parent node IDs for a given node.

func (*SBOMGraph) GetRootID 

func (g *SBOMGraph) GetRootID() string

GetRootID returns the ID of the current scope root.

func (*SBOMGraph) HasInfoSource 

func (g *SBOMGraph) HasInfoSource(infoSourceID string) bool

HasInfoSource checks if an info source exists in the graph.

func (*SBOMGraph) InfoSources 

func (g *SBOMGraph) InfoSources() iter.Seq[*GraphNode]

InfoSources returns all information source nodes reachable from scope.

func (*SBOMGraph) IsReachable added in v1.3.0 

func (g *SBOMGraph) IsReachable(id string) bool

func (*SBOMGraph) IsScoped 

func (g *SBOMGraph) IsScoped() bool

func (*SBOMGraph) LicenseDistribution 

func (g *SBOMGraph) LicenseDistribution() map[string]int

func (*SBOMGraph) MakeValid added in v1.9.0 

func (g *SBOMGraph) MakeValid()

MakeValid prunes unidentifiable components (see pruneUnidentifiablePackages). Call this once after building a graph via InvalidSBOMGraphFromCycloneDX and doing any enrichment (EnrichSBOM) on it.

func (*SBOMGraph) MergeGraph 

func (g *SBOMGraph) MergeGraph(other *SBOMGraph) GraphDiff

MergeGraph merges another graph into this one, returning the diff. Artifacts from the other graph are added/merged under this graph's root. When an info source with the same ID exists, it replaces the entire subtree.

func (*SBOMGraph) MinimalTreeToPURL 

func (g *SBOMGraph) MinimalTreeToPURL(purl string, maxDepth int) minimalTree

MinimalTreeToPURL returns a minimal tree structure containing only the subgraph of nodes that lead to the specified PURL. This collects all ancestor nodes without enumerating individual paths, avoiding combinatorial explosion. The maxDepth parameter limits how far back we traverse (0 = unlimited).

func (*SBOMGraph) Node 

func (g *SBOMGraph) Node(id string) *GraphNode

Node returns a node by ID, or nil if not reachable from scope.

func (*SBOMGraph) NodeIDsAndEdges 

func (g *SBOMGraph) NodeIDsAndEdges() FlatGraph

NodeIDsAndEdges returns all node IDs and edges reachable from the current scope.

func (*SBOMGraph) NodesOfType 

func (g *SBOMGraph) NodesOfType(nodeType GraphNodeType) iter.Seq[*GraphNode]

NodesOfType returns all reachable nodes of a specific type.

func (*SBOMGraph) Scope 

func (g *SBOMGraph) Scope(id string) error

func (*SBOMGraph) ScopeToArtifact 

func (g *SBOMGraph) ScopeToArtifact(artifactName string) error

func (*SBOMGraph) ScopeToInfoSource 

func (g *SBOMGraph) ScopeToInfoSource(infoSource string, t InfoSourceType) error

func (*SBOMGraph) ToCycloneDX 

func (g *SBOMGraph) ToCycloneDX(metadata BOMMetadata) *cdx.BOM

ToCycloneDX exports the scoped view as a CycloneDX BOM.

func (*SBOMGraph) ToMinimalTree 

func (g *SBOMGraph) ToMinimalTree() minimalTree

type VersionInterpretationType 

type VersionInterpretationType string
const (
	ExactVersionString       VersionInterpretationType = "exact"
	SemanticVersionString    VersionInterpretationType = "semver_range"
	EmptyVersion             VersionInterpretationType = "empty_version"
	EcosystemSpecificVersion VersionInterpretationType = "ecosystem_specific"
)

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.