sdk

package
v0.14.2 Latest Latest
Warning

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

 Go to latest Published: Jun 16, 2026 License: Apache-2.0 Imports: 25 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// EnvHTTPProxy is Bomly's explicit outbound HTTP proxy environment variable.
	EnvHTTPProxy = "BOMLY_HTTP_PROXY"
	// EnvHTTPNoProxy is Bomly's explicit proxy bypass list environment variable.
	EnvHTTPNoProxy = "BOMLY_HTTP_NO_PROXY"
	// EnvHTTPProxyType is Bomly's explicit outbound proxy type.
	EnvHTTPProxyType = "BOMLY_HTTP_PROXY_TYPE"
	// EnvHTTPProxyHost is Bomly's explicit outbound proxy host.
	EnvHTTPProxyHost = "BOMLY_HTTP_PROXY_HOST"
	// EnvHTTPProxyPort is Bomly's explicit outbound proxy port.
	EnvHTTPProxyPort = "BOMLY_HTTP_PROXY_PORT"
	// EnvHTTPProxyUsername is Bomly's explicit outbound proxy username.
	EnvHTTPProxyUsername = "BOMLY_HTTP_PROXY_USERNAME"
	// EnvHTTPProxyPassword is Bomly's explicit outbound proxy password.
	EnvHTTPProxyPassword = "BOMLY_HTTP_PROXY_PASSWORD"
	// EnvHTTPCACertFile points to an additional PEM certificate chain for outbound HTTPS.
	EnvHTTPCACertFile = "BOMLY_HTTP_CA_CERT_FILE"
	// EnvPluginConfigFile points external plugins at their per-plugin JSON config.
	EnvPluginConfigFile = "BOMLY_PLUGIN_CONFIG_FILE"
	// EnvPluginID identifies the managed plugin currently being executed.
	EnvPluginID = "BOMLY_PLUGIN_ID"
)
View Source 
const (
	ExploitabilityValueExploitable = "exploitable"
)

ExploitabilityValueExploitable constraint values currently supported.

View Source 
const InstalledPluginsSchemaVersion = "bomly.installed-plugins.v1"

InstalledPluginsSchemaVersion is the installed plugin database schema version.

View Source 
const MetadataKeyDetectionLicenses = "bomly.detection.licenses"

MetadataKeyDetectionLicenses is the Dependency.Metadata key under which detectors that discover license facts at detection time (e.g. SBOM-backed detectors) stash []PackageLicense for consolidation to lift into the package registry.

View Source 
const MetadataKeyNPM = "npm"

MetadataKeyNPM is the Metadata map key for *NPMPackageMetadata.

View Source 
const PackageManifestSchemaVersion = "bomly.plugin.package.v1"

PackageManifestSchemaVersion is the package manifest schema version.

View Source 
const PluginAPIVersion = "bomly.plugin.v1"

PluginAPIVersion is the current managed plugin API contract version.

View Source 
const (
	ReachabilityValueReachable = "reachable"
)

ReachabilityValueReachable constraint values currently supported.

View Source 
const RuntimeDescriptorSnapshotSchemaVersion = "bomly.plugin.runtime-descriptor.v1"

RuntimeDescriptorSnapshotSchemaVersion is Bomly's internal installed descriptor snapshot schema.

View Source 
const RuntimeHashiCorpGRPC = "hashicorp-grpc"

RuntimeHashiCorpGRPC identifies the supported external plugin runtime.

Variables

View Source 
var (
	ErrNilNode          = errors.New("dependency node is nil")
	ErrEmptyNodeID      = errors.New("dependency node id is empty")
	ErrNodeAlreadyExist = errors.New("dependency node already exists")
	ErrNodeNotFound     = errors.New("dependency node not found")
	ErrSelfDependency   = errors.New("self dependency is not allowed")
	ErrCycleDetected    = errors.New("dependency creates a cycle")
)

Functions

func BuildPackageURL 

func BuildPackageURL(purlType, namespace, name, version string) string

BuildPackageURL builds and normalizes a package URL from its parts.

func CanonicalPackageURLFromDependency 

func CanonicalPackageURLFromDependency(dep *Dependency) string

CanonicalPackageURLFromDependency returns the canonical package URL for dep.

func CanonicalPackageURLFromParts 

func CanonicalPackageURLFromParts(existingPURL string, ecosystem Ecosystem, packageManager PackageManager, typ PackageType, org, name, version string) string

CanonicalPackageURLFromParts returns the canonical package URL derived from raw identity fields. existingPURL takes precedence when it canonicalizes.

func CanonicalizePackageURL 

func CanonicalizePackageURL(value string) string

CanonicalizePackageURL normalizes a package URL string when possible.

func ClientPluginMap 

func ClientPluginMap() map[string]hplugin.Plugin

ClientPluginMap returns the client-side plugin map used by Bomly core.

func DecodePluginConfigFromEnv 

func DecodePluginConfigFromEnv(target any) error

DecodePluginConfigFromEnv decodes the per-plugin JSON config file into target.

func HandshakeConfig 

func HandshakeConfig() hplugin.HandshakeConfig

HandshakeConfig returns the shared HashiCorp go-plugin handshake configuration.

func MergeGraph 

func MergeGraph(dst, src *Graph) error

MergeGraph adds all nodes and relationships from src into dst.

func NewHTTPClient 

func NewHTTPClient(config HTTPClientConfig) (*http.Client, error)

NewHTTPClient creates an outbound HTTP client using Go's default transport behavior plus Bomly's proxy configuration.

func NodeIsDiffable 

func NodeIsDiffable(node *Dependency) bool

NodeIsDiffable reports whether node should participate in dependency diffs.

func NormalizeDependencyIdentity 

func NormalizeDependencyIdentity(pkg *Dependency)

NormalizeDependencyIdentity applies ecosystem-aware identity normalization in place.

func PackageURLBase 

func PackageURLBase(value string) string

PackageURLBase strips version and qualifiers from a package URL.

func PackageURLTypeForValues 

func PackageURLTypeForValues(values ...any) string

PackageURLTypeForValues maps ecosystem/build-system values to a package-url type.

func ParsePackageURL 

func ParsePackageURL(value string) *packageurl.PackageURL

ParsePackageURL parses a package URL string.

func RawPluginConfigFromEnv 

func RawPluginConfigFromEnv() ([]byte, error)

RawPluginConfigFromEnv reads the per-plugin JSON config file named by BOMLY_PLUGIN_CONFIG_FILE. It returns nil when no plugin config file is set.

func ServeAuditor 

func ServeAuditor(auditor ServedAuditor)

ServeAuditor serves an auditor plugin over HashiCorp go-plugin gRPC transport.

func ServeDetector 

func ServeDetector(detector ServedDetector)

ServeDetector serves a detector plugin over HashiCorp go-plugin gRPC transport.

func ServeMatcher 

func ServeMatcher(matcher ServedMatcher)

ServeMatcher serves a matcher plugin over HashiCorp go-plugin gRPC transport.

func SetDetectionLicenses 

func SetDetectionLicenses(dep *Dependency, licenses []PackageLicense)

SetDetectionLicenses stashes detection-time license facts on dep's metadata under MetadataKeyDetectionLicenses, so consolidation can lift them into the package registry. No-op when dep is nil or licenses is empty.

func SeverityMeets 

func SeverityMeets(candidate SeverityLevel, threshold string) bool

SeverityMeets reports whether candidate's severity is at or above threshold. Threshold "any" matches every candidate, including unknown.

func SeverityRank 

func SeverityRank(severity SeverityLevel) int

SeverityRank returns a comparable rank for a severity string. Unknown / empty values rank below "low".

func ValidateAuditorDescriptor 

func ValidateAuditorDescriptor(descriptor *AuditorDescriptor) error

ValidateAuditorDescriptor validates typed auditor registration data.

func ValidateDetectorDescriptor 

func ValidateDetectorDescriptor(descriptor *DetectorDescriptor) error

ValidateDetectorDescriptor validates typed detector registration data.

func ValidateMatcherDescriptor 

func ValidateMatcherDescriptor(descriptor *MatcherDescriptor) error

ValidateMatcherDescriptor validates typed matcher registration data.

Types

type Affected 

type Affected struct {
	Ranges            []VersionRange `json:"ranges,omitempty"`
	Versions          []string       `json:"versions,omitempty"`
	EcosystemSpecific map[string]any `json:"ecosystem_specific,omitempty"`
	DatabaseSpecific  map[string]any `json:"database_specific,omitempty"`
}

Affected describes one OSV affected entry: the version ranges and explicit versions impacted by the vulnerability.

type AffectedSymbol 

type AffectedSymbol struct {
	Symbol     string          `json:"symbol,omitempty"`
	Kind       SymbolKind      `json:"kind,omitempty"`
	Package    string          `json:"package,omitempty"`
	Module     string          `json:"module,omitempty"`
	Definition *SourcePosition `json:"definition,omitempty"`
}

AffectedSymbol identifies one vulnerable symbol within a package. Matchers that have symbol-level data populate this on a Vulnerability; reachability analyzers use it to know which symbols to look for in app code.

func (AffectedSymbol) Clone 

func (s AffectedSymbol) Clone() AffectedSymbol

Clone returns a deep copy of the affected symbol.

type AnalyzeRequest 

type AnalyzeRequest struct {
	ProjectPath     string           `json:"projectPath,omitempty"`
	ExecutionTarget ExecutionTarget  `json:"executionTarget"`
	SubprojectInfo  Subproject       `json:"subprojectInfo"`
	Ecosystem       Ecosystem        `json:"ecosystem,omitempty"`
	PackageManager  PackageManager   `json:"packageManager,omitempty"`
	Language        Language         `json:"language,omitempty"`
	Query           PackageQuery     `json:"query"`
	Graph           *Graph           `json:"graph,omitempty"`
	Registry        *PackageRegistry `json:"registry,omitempty"`
	Target          *Dependency      `json:"target,omitempty"`
	AnalyzerFilter  AnalyzerFilter   `json:"analyzerFilter"`
	Stderr          io.Writer        `json:"-"`
}

AnalyzeRequest defines input for an analyzer. Analyzers annotate Vulnerability.Reachability on packages in the Registry.

type AnalyzeResponse 

type AnalyzeResponse = AnalyzeResult

AnalyzeResponse is the analyzer response payload exposed to plugins.

type AnalyzeResult 

type AnalyzeResult struct {
	Registry      *PackageRegistry             `json:"registry,omitempty"`
	AnalyzerRuns  []string                     `json:"analyzerRuns,omitempty"`
	AnalyzerStats map[string]ReachabilityStats `json:"analyzerStats,omitempty"`
}

AnalyzeResult contains the registry after analyzer enrichment.

type Analyzer 

type Analyzer interface {
	Descriptor() AnalyzerDescriptor
	Ready() bool
	Applicable(context.Context, AnalyzeRequest) (bool, error)
	Analyze(context.Context, AnalyzeRequest) (AnalyzeResult, error)
}

Analyzer enriches Vulnerability entries with reachability data derived from code analysis. Analyzers run after matchers, before auditors, and must never abort the pipeline on failure.

type AnalyzerDescriptor 

type AnalyzerDescriptor struct {
	Name                string           `json:"name"`
	DisplayName         string           `json:"displayName,omitempty"`
	Aliases             []string         `json:"aliases,omitempty"`
	Tags                []string         `json:"tags,omitempty"`
	SupportedEcosystems []Ecosystem      `json:"supportedEcosystems,omitempty"`
	SupportedManagers   []PackageManager `json:"supportedManagers,omitempty"`
	// SupportedLanguages is the analyzer's primary dispatch axis.
	SupportedLanguages []Language `json:"supportedLanguages,omitempty"`
	// SupportedTiers communicates the precision the analyzer can deliver.
	SupportedTiers []ReachabilityTier `json:"supportedTiers,omitempty"`
}

AnalyzerDescriptor describes an analyzer registration.

func (AnalyzerDescriptor) Label 

func (d AnalyzerDescriptor) Label() string

Label returns the user-facing analyzer label, falling back to Name.

type AnalyzerFilter 

type AnalyzerFilter struct {
	Include []string
	Exclude []string
}

AnalyzerFilter narrows analyzer selection for a request.

func (AnalyzerFilter) Excludes 

func (f AnalyzerFilter) Excludes(name string) bool

Excludes reports whether an analyzer name is explicitly denied.

func (AnalyzerFilter) Includes 

func (f AnalyzerFilter) Includes(name string) bool

Includes reports whether an analyzer name is explicitly allowed.

type ApplicableResponse 

type ApplicableResponse struct {
	Applicable bool `json:"applicable"`
}

ApplicableResponse reports whether a plugin should run for the given request.

type AuditRequest 

type AuditRequest struct {
	ProjectPath     string           `json:"projectPath,omitempty"`
	ExecutionTarget ExecutionTarget  `json:"executionTarget"`
	SubprojectInfo  Subproject       `json:"subprojectInfo"`
	Ecosystem       Ecosystem        `json:"ecosystem,omitempty"`
	PackageManager  PackageManager   `json:"packageManager,omitempty"`
	Query           PackageQuery     `json:"query"`
	Graph           *Graph           `json:"graph,omitempty"`
	BaselineGraph   *Graph           `json:"baselineGraph,omitempty"`
	Registry        *PackageRegistry `json:"registry,omitempty"`
	Target          *Dependency      `json:"target,omitempty"`
	AuditorFilter   AuditorFilter    `json:"auditorFilter"`
	Stderr          io.Writer        `json:"-"`
}

AuditRequest defines input for an auditor. Auditors read the dependency Graph and the package Registry and emit reference-style findings.

type AuditResponse 

type AuditResponse = AuditResult

AuditResponse is the auditor response payload exposed to plugins.

type AuditResult 

type AuditResult struct {
	Findings        []Finding      `json:"findings,omitempty"`
	RiskScores      []RiskScore    `json:"riskScores,omitempty"`
	AuditorRuns     []string       `json:"auditorRuns,omitempty"`
	AuditorFindings map[string]int `json:"auditorFindings,omitempty"`
}

AuditResult contains findings and scores from one auditor.

type Auditor 

type Auditor interface {
	Descriptor() AuditorDescriptor
	Ready() bool
	Applicable(context.Context, AuditRequest) (bool, error)
	Audit(context.Context, AuditRequest) (AuditResult, error)
}

Auditor analyzes graphs or components and returns findings.

type AuditorDescriptor 

type AuditorDescriptor struct {
	Name                string           `json:"name"`
	DisplayName         string           `json:"displayName,omitempty"`
	Aliases             []string         `json:"aliases,omitempty"`
	Tags                []string         `json:"tags,omitempty"`
	SupportedEcosystems []Ecosystem      `json:"supportedEcosystems,omitempty"`
	SupportedManagers   []PackageManager `json:"supportedManagers,omitempty"`
}

AuditorDescriptor describes an auditor registration.

func (AuditorDescriptor) Label 

func (d AuditorDescriptor) Label() string

Label returns the user-facing auditor label, falling back to Name.

type AuditorFilter 

type AuditorFilter struct {
	Include []string
	Exclude []string
}

AuditorFilter narrows auditor selection for a request.

func (AuditorFilter) Excludes 

func (f AuditorFilter) Excludes(name string) bool

Excludes reports whether an auditor name is explicitly denied.

func (AuditorFilter) Includes 

func (f AuditorFilter) Includes(name string) bool

Includes reports whether an auditor name is explicitly allowed.

type CVSSScore 

type CVSSScore struct {
	Vector  string       `json:"vector,omitempty"`
	Score   float64      `json:"score,omitempty"`
	Version SeverityType `json:"version,omitempty"`
	Source  string       `json:"source,omitempty"`
}

CVSSScore captures one CVSS vector and score.

type CWE 

type CWE struct {
	CVE    string `json:"cve,omitempty"`
	ID     string `json:"id,omitempty"`
	Source string `json:"source,omitempty"`
	Type   string `json:"type,omitempty"`
}

CWE identifies a Common Weakness Enumeration entry for a vulnerability.

type CallFrame 

type CallFrame struct {
	Function string         `json:"function,omitempty"`
	Package  string         `json:"package,omitempty"`
	Receiver string         `json:"receiver,omitempty"`
	Position SourcePosition `json:"position,omitempty"`
}

CallFrame represents one stack frame in a reachability call path.

type CallPath 

type CallPath struct {
	Sink   AffectedSymbol `json:"sink"`
	Frames []CallFrame    `json:"frames,omitempty"`
}

CallPath is one entry-point → sink path. Frames[0] is the entry point.

func (CallPath) Clone 

func (p CallPath) Clone() CallPath

Clone returns a deep copy of the call path.

type Client 

type Client interface {
	DetectorDescriptor(context.Context) (*DetectorDescriptor, error)
	DetectorPackageManagerSupport(context.Context) ([]PackageManagerSupport, error)
	DetectorReady(context.Context, *DetectRequest) (*ReadyResponse, error)
	DetectorApplicable(context.Context, *DetectRequest) (*ApplicableResponse, error)
	DetectorInstall(context.Context, *DetectRequest) (*InstallResponse, error)
	Detect(context.Context, *DetectRequest) (*DetectResponse, error)
	MatcherDescriptor(context.Context) (*MatcherDescriptor, error)
	MatcherReady(context.Context, *MatchRequest) (*ReadyResponse, error)
	MatcherApplicable(context.Context, *MatchRequest) (*ApplicableResponse, error)
	Match(context.Context, *MatchRequest) (*MatchResponse, error)
	AuditorDescriptor(context.Context) (*AuditorDescriptor, error)
	AuditorReady(context.Context, *AuditRequest) (*ReadyResponse, error)
	AuditorApplicable(context.Context, *AuditRequest) (*ApplicableResponse, error)
	Audit(context.Context, *AuditRequest) (*AuditResponse, error)
}

Client is the generic runtime client used by Bomly core.

type ComponentDescriptor 

type ComponentDescriptor struct {
	Name                string           `json:"name"`
	DisplayName         string           `json:"displayName,omitempty"`
	Aliases             []string         `json:"aliases,omitempty"`
	Tags                []string         `json:"tags,omitempty"`
	SupportedEcosystems []Ecosystem      `json:"supportedEcosystems,omitempty"`
	SupportedManagers   []PackageManager `json:"supportedManagers,omitempty"`
}

ComponentDescriptor describes the common identity and selection fields shared by detectors, matchers, auditors, and analyzers.

func (ComponentDescriptor) Label 

func (d ComponentDescriptor) Label() string

Label returns the user-facing component label, falling back to Name.

type ConsolidatedGraph 

type ConsolidatedGraph struct {
	ExecutionTarget ExecutionTarget
	Graphs          *GraphContainer
	Manifests       []ConsolidatedManifest
	Subprojects     []ConsolidatedSubproject
}

ConsolidatedGraph describes a merged view above per-subproject graph results.

type ConsolidatedManifest 

type ConsolidatedManifest struct {
	Entry          GraphEntry
	Subproject     Subproject
	DetectorName   string
	Origin         DetectorOrigin
	Technique      DetectorTechnique
	RootManifestID string
}

ConsolidatedManifest describes one selected manifest after detector-level deduplication and precedence rules have been applied.

type ConsolidatedSubproject 

type ConsolidatedSubproject struct {
	Subproject      Subproject
	DetectorName    string
	RootManifestIDs []string
}

ConsolidatedSubproject describes one subproject included in a consolidated graph.

type Coordinates added in v0.13.0 

type Coordinates struct {
	PURL           string         `json:"purl,omitempty"`
	Ecosystem      Ecosystem      `json:"ecosystem,omitempty"`
	PackageManager PackageManager `json:"package_manager,omitempty"`
	Type           PackageType    `json:"type,omitempty"`
	Org            string         `json:"org,omitempty"`
	Name           string         `json:"name,omitempty"`
	Version        string         `json:"version,omitempty"`
	Language       Language       `json:"language,omitempty"`
}

Coordinates is the shared coordinates view for manifest dependencies and matched registry packages. It intentionally excludes graph-only fields (scopes, locations, package refs) and enrichment-only fields (licenses, vulnerabilities, scorecard) so Dependency and Package remain distinct domain models.

func (Coordinates) CanonicalPURL added in v0.13.0 

func (i Coordinates) CanonicalPURL() string

CanonicalPURL returns the canonical package URL for the identity.

func (Coordinates) IdentityKey added in v0.13.0 

func (i Coordinates) IdentityKey() string

IdentityKey returns a stable package identity without version information.

func (Coordinates) QualifiedName added in v0.13.0 

func (i Coordinates) QualifiedName() string

QualifiedName returns the package name prefixed with its organization when present.

func (Coordinates) StableID added in v0.13.0 

func (i Coordinates) StableID() string

StableID returns a graph-friendly identifier derived from name and version.

type Dependency 

type Dependency struct {
	Coordinates
	ID          string            `json:"id"`
	Scopes      []Scope           `json:"scopes,omitempty"`
	Locations   []PackageLocation `json:"locations,omitempty"`
	CPEs        []string          `json:"cpes,omitempty"`
	Digests     []Digest          `json:"digests,omitempty"`
	Copyright   string            `json:"copyright,omitempty"`
	FoundBy     string            `json:"found_by,omitempty"`
	ResolvedURL string            `json:"resolved_url,omitempty"`
	Metadata    map[string]any    `json:"metadata,omitempty"`

	// Matched is true when the referenced package was enriched by a matcher.
	Matched bool `json:"matched,omitempty"`
	// PackageRef is the PURL of this dependency's matching artifact.
	PackageRef string `json:"package_ref,omitempty"`
}

Dependency is one node in a manifest's directed dependency graph: a detected dependency instance with identity, detection metadata, and a reference to its matching artifact (Package) by PURL. Matching enrichment (licenses, vulnerabilities, scorecard) lives on the referenced Package, not here.

func NewDependency 

func NewDependency(dep Dependency) *Dependency

NewDependency constructs a dependency node, deriving its ID from identity.

func NewDependencyRef 

func NewDependencyRef(name, version string) *Dependency

NewDependencyRef constructs a dependency from a name and version. If version is set, ID is "name@version"; otherwise ID is "name".

func NewDependencyRefWithID 

func NewDependencyRefWithID(id, name, version string) *Dependency

NewDependencyRefWithID constructs a dependency with a custom ID.

func NewDependencyWithID 

func NewDependencyWithID(id string, dep Dependency) *Dependency

NewDependencyWithID constructs a dependency node with a custom ID.

func (*Dependency) AddScope 

func (d *Dependency) AddScope(scope Scope)

AddScope records a scope on the dependency if not already present.

func (*Dependency) Clone 

func (d *Dependency) Clone() *Dependency

Clone returns a deep copy of the dependency.

func (*Dependency) DisplayName 

func (d *Dependency) DisplayName() string

DisplayName returns the most human-friendly identifier available.

func (*Dependency) HasScope 

func (d *Dependency) HasScope(scope Scope) bool

HasScope reports whether the dependency carries the given scope.

func (*Dependency) IdentityKey 

func (d *Dependency) IdentityKey() string

IdentityKey returns a stable identity without version information.

func (*Dependency) PrimaryScope 

func (d *Dependency) PrimaryScope() Scope

PrimaryScope returns the merged precedence scope across all recorded scopes.

func (*Dependency) QualifiedName 

func (d *Dependency) QualifiedName() string

QualifiedName returns the name prefixed with its organization when present.

func (*Dependency) StableID 

func (d *Dependency) StableID() string

StableID returns the stable graph identifier for the dependency.

func (*Dependency) WithoutID 

func (d *Dependency) WithoutID() Dependency

WithoutID returns the dependency data without the precomputed graph ID.

type DependencyEdge 

type DependencyEdge struct {
	FromID string `json:"fromId"`
	ToID   string `json:"toId"`
}

DependencyEdge captures one directed relationship between node IDs.

type DependencyQuery 

type DependencyQuery struct {
	Name string `json:"name,omitempty"`
	ID   string `json:"id,omitempty"`
}

DependencyQuery identifies a specific component target.

type DetectRequest 

type DetectRequest = DetectionRequest

DetectRequest is the detector request payload exposed to plugins.

type DetectResponse 

type DetectResponse = DetectionResult

DetectResponse is the detector response payload exposed to plugins.

type DetectionRequest 

type DetectionRequest struct {
	ProjectPath     string          `json:"projectPath,omitempty"`
	ExecutionTarget ExecutionTarget `json:"executionTarget"`
	Subproject      Subproject      `json:"subproject"`
	Ecosystem       Ecosystem       `json:"ecosystem,omitempty"`
	PackageManager  PackageManager  `json:"packageManager,omitempty"`
	// EnrichmentEnabled allows orchestration to request detector-time metadata
	// enrichment when a downstream command has opted into package enrichment.
	EnrichmentEnabled  bool            `json:"enrichmentEnabled,omitempty"`
	DetectorFilter     DetectorFilter  `json:"detectorFilter"`
	ScopeFilter        Scope           `json:"scopeFilter,omitempty"`
	Query              DependencyQuery `json:"query"`
	InstallFirst       bool            `json:"installFirst,omitempty"`
	InstallArgs        []string        `json:"installArgs,omitempty"`
	CoreVersion        string          `json:"coreVersion,omitempty"`
	AllowStdErrLogging bool            `json:"allowStdErrLogging,omitempty"`
	Stderr             io.Writer       `json:"-"`
	Verbose            bool            `json:"-"`
}

DetectionRequest defines input for dependency graph resolution.

type DetectionResult 

type DetectionResult struct {
	SubprojectInfo      Subproject        `json:"subprojectInfo"`
	RootExecutionTarget ExecutionTarget   `json:"rootExecutionTarget"`
	DetectorName        string            `json:"detectorName,omitempty"`
	Origin              DetectorOrigin    `json:"origin,omitempty"`
	Technique           DetectorTechnique `json:"technique,omitempty"`
	Graphs              *GraphContainer   `json:"graphs,omitempty"`
}

DetectionResult contains one or more manifest-scoped graphs.

func FilterDetectionResultByScope 

func FilterDetectionResultByScope(result DetectionResult, scope Scope) (DetectionResult, error)

FilterDetectionResultByScope applies scope filtering to each graph entry in a detector result.

func (DetectionResult) ConsolidatedGraph 

func (r DetectionResult) ConsolidatedGraph() (*Graph, error)

ConsolidatedGraph returns a single graph view for the resolve result.

type Detector 

type Detector interface {
	Descriptor() DetectorDescriptor
	PackageManagerSupport() []PackageManagerSupport
	Ready() bool
	Applicable(context.Context, DetectionRequest) (bool, error)
	ResolveGraph(context.Context, DetectionRequest) (DetectionResult, error)
}

Detector resolves dependency information.

type DetectorDescriptor 

type DetectorDescriptor struct {
	Name                  string                  `json:"name"`
	DisplayName           string                  `json:"displayName,omitempty"`
	Aliases               []string                `json:"aliases,omitempty"`
	Tags                  []string                `json:"tags,omitempty"`
	SupportedEcosystems   []Ecosystem             `json:"supportedEcosystems,omitempty"`
	SupportedManagers     []PackageManager        `json:"supportedManagers,omitempty"`
	Technique             DetectorTechnique       `json:"technique,omitempty"`
	PackageManagerSupport []PackageManagerSupport `json:"packageManagerSupport,omitempty"`
	FallbackDetectors     []string                `json:"fallbackDetectors,omitempty"`
	SupportsInstallFirst  bool                    `json:"supportsInstallFirst,omitempty"`
}

DetectorDescriptor describes a detector registration.

func (DetectorDescriptor) Label 

func (d DetectorDescriptor) Label() string

Label returns the user-facing detector label, falling back to Name.

type DetectorFilter 

type DetectorFilter struct {
	Include []string
	Exclude []string
}

DetectorFilter narrows detector selection for a request.

func (DetectorFilter) Excludes 

func (f DetectorFilter) Excludes(name string) bool

Excludes reports whether a detector name is explicitly denied.

func (DetectorFilter) Includes 

func (f DetectorFilter) Includes(name string) bool

Includes reports whether a detector name is explicitly allowed.

type DetectorInstaller 

type DetectorInstaller interface {
	Install(context.Context, *DetectRequest) (*InstallResponse, error)
}

DetectorInstaller optionally performs install-first preparation before detection.

type DetectorOrigin 

type DetectorOrigin string

DetectorOrigin describes where a detector, matcher, or auditor is sourced from. 

const (
	// CoreOrigin identifies components implemented directly in Bomly's own codebase.
	CoreOrigin DetectorOrigin = "core"
	// BundledOrigin identifies third-party components that are compiled into the Bomly binary (e.g. Syft, Grype).
	BundledOrigin DetectorOrigin = "bundled"
	// ExternalOrigin identifies components loaded as external plugins at runtime.
	ExternalOrigin DetectorOrigin = "external"
)

type DetectorTechnique 

type DetectorTechnique string

DetectorTechnique describes the resolution strategy used by a detector. Only meaningful for detectors; matchers and auditors leave this empty. 

const (
	// ManifestTechnique reads a declarative dependency manifest file (e.g. package.json, Gemfile).
	ManifestTechnique DetectorTechnique = "manifest"
	// LockfileTechnique parses a deterministic lockfile (e.g. package-lock.json, yarn.lock).
	LockfileTechnique DetectorTechnique = "lockfile"
	// BuildToolTechnique invokes a build tool to resolve the live dependency graph.
	BuildToolTechnique DetectorTechnique = "build-tool"
	// SBOMTechnique ingests an existing SBOM document.
	SBOMTechnique DetectorTechnique = "sbom"
	// BinaryTechnique analyses a compiled binary or installed artifact.
	BinaryTechnique DetectorTechnique = "binary"
	// ContainerTechnique inspects a container image.
	ContainerTechnique DetectorTechnique = "container"
	// MultipleTechnique applies several of the above strategies depending on the target.
	MultipleTechnique DetectorTechnique = "multiple"
)

type Diff 

type Diff struct {
	Added   []*Dependency
	Removed []*Dependency
	Updated []VersionChange
}

Diff summarizes the dependency changes between two graphs.

func Compare 

func Compare(base, head *Graph) Diff

Compare returns the added, removed, and updated dependencies between base and head. Synthetic consolidated subproject nodes are ignored.

type Digest 

type Digest struct {
	Algorithm DigestAlgorithm `json:"algorithm,omitempty"`
	Value     string          `json:"value,omitempty"`
}

Digest captures integrity information for a package artifact.

type DigestAlgorithm added in v0.13.0 

type DigestAlgorithm string

DigestAlgorithm identifies an artifact digest algorithm. 

const (
	DigestAlgorithmSHA1   DigestAlgorithm = "sha1"
	DigestAlgorithmSHA256 DigestAlgorithm = "sha256"
)

type EPSSScore 

type EPSSScore struct {
	CVE        string  `json:"cve,omitempty"`
	EPSS       float64 `json:"epss"`
	Percentile float64 `json:"percentile,omitempty"`
	Date       string  `json:"date,omitempty"`
}

EPSSScore captures Exploit Prediction Scoring System data for a vulnerability.

type Ecosystem 

type Ecosystem string

Ecosystem groups package managers under a registry-specific dependency model. 

const (
	EcosystemUnknown   Ecosystem = ""
	EcosystemNPM       Ecosystem = "npm"
	EcosystemMaven     Ecosystem = "maven"
	EcosystemGo        Ecosystem = "go"
	EcosystemPython    Ecosystem = "python"
	EcosystemALPM      Ecosystem = "alpm"
	EcosystemAPK       Ecosystem = "apk"
	EcosystemCPP       Ecosystem = "cpp"
	EcosystemConda     Ecosystem = "conda"
	EcosystemDart      Ecosystem = "dart"
	EcosystemDPKG      Ecosystem = "dpkg"
	EcosystemElixir    Ecosystem = "elixir"
	EcosystemErlang    Ecosystem = "erlang"
	EcosystemGitHub    Ecosystem = "github-actions"
	EcosystemHaskell   Ecosystem = "haskell"
	EcosystemHomebrew  Ecosystem = "homebrew"
	EcosystemLua       Ecosystem = "lua"
	EcosystemDotNet    Ecosystem = "dotnet"
	EcosystemNix       Ecosystem = "nix"
	EcosystemOCaml     Ecosystem = "ocaml"
	EcosystemPHP       Ecosystem = "php"
	EcosystemPortage   Ecosystem = "portage"
	EcosystemProlog    Ecosystem = "prolog"
	EcosystemR         Ecosystem = "r"
	EcosystemRPM       Ecosystem = "rpm"
	EcosystemRuby      Ecosystem = "ruby"
	EcosystemRust      Ecosystem = "rust"
	EcosystemScala     Ecosystem = "scala"
	EcosystemSBOM      Ecosystem = "sbom"
	EcosystemSnap      Ecosystem = "snap"
	EcosystemSwift     Ecosystem = "swift"
	EcosystemTerraform Ecosystem = "terraform"
	EcosystemWordPress Ecosystem = "wordpress"
	EcosystemOther     Ecosystem = "other"
)

Keep this list aligned with the Syft-backed support matrix in docs/SUPPORT_MATRIX.md and the Syft manifest mappings in internal/detectors/syft/detector.go.

func ParseEcosystem 

func ParseEcosystem(value string) (Ecosystem, error)

ParseEcosystem normalizes a user-provided ecosystem value.

func (Ecosystem) String added in v0.13.0 

func (e Ecosystem) String() string

String returns the ecosystem value.

type EcosystemFilter 

type EcosystemFilter struct {
	Include []Ecosystem
	Exclude []Ecosystem
}

EcosystemFilter specifies inclusion and exclusion rules for filtering ecosystems.

func (EcosystemFilter) Excludes 

func (f EcosystemFilter) Excludes(name Ecosystem) bool

Excludes reports whether a detector name is explicitly denied.

func (EcosystemFilter) Includes 

func (f EcosystemFilter) Includes(name Ecosystem) bool

Includes reports whether a detector name is explicitly allowed.

type ExecutionTarget 

type ExecutionTarget struct {
	Kind          ExecutionTargetKind `json:"kind,omitempty"`
	Location      string              `json:"location,omitempty"`
	RepositoryURL string              `json:"repositoryUrl,omitempty"`
	Ref           string              `json:"ref,omitempty"`
}

type ExecutionTargetKind 

type ExecutionTargetKind string

ExecutionTargetKind identifies the top-level source selected by the user for one scan execution. 

const (
	// ExecutionTargetFilesystem points at a local filesystem path. The path may be a
	// directory or a single file depending on the selected scan target.
	ExecutionTargetFilesystem ExecutionTargetKind = "filesystem"
	// ExecutionTargetWorkingDirectory is kept as an alias for the existing local-path model.
	ExecutionTargetWorkingDirectory ExecutionTargetKind = ExecutionTargetFilesystem
	ExecutionTargetGitRepository    ExecutionTargetKind = "git-repository"
	ExecutionTargetContainerImage   ExecutionTargetKind = "container-image"
)

type FailOnConstraint 

type FailOnConstraint struct {
	Kind  FailOnKind
	Value string
}

FailOnConstraint is one parsed --fail-on value. The policy auditor evaluates a vulnerability against an AND-set of constraints; only vulnerabilities satisfying every constraint become Findings.

func ParseFailOn 

func ParseFailOn(raw string) (FailOnConstraint, error)

ParseFailOn parses one raw --fail-on value into a typed constraint. Severity tokens (any|low|medium|high|critical) yield a SeverityConstraint. "reachable" yields a ReachabilityConstraint. "exploitable" yields an ExploitabilityConstraint. Empty input returns the zero value with no error so callers can treat empty repeats as no-ops.

func ParseFailOnList 

func ParseFailOnList(raws []string) ([]FailOnConstraint, error)

ParseFailOnList parses every raw value, skipping empty entries. It returns an aggregate error if any value is invalid; valid constraints are still returned alongside the error so callers can surface partial diagnostics.

func (FailOnConstraint) String 

func (c FailOnConstraint) String() string

String returns a stable string form for the constraint, suitable for debug logs and error messages.

type FailOnKind 

type FailOnKind string

FailOnKind classifies one --fail-on constraint. 

const (
	// SeverityConstraint matches when a finding's severity is at or above
	// the constraint Value (any|low|medium|high|critical).
	SeverityConstraint FailOnKind = "severity"
	// ReachabilityConstraint matches when a vulnerability's reachability
	// status equals the constraint Value (currently only "reachable").
	ReachabilityConstraint FailOnKind = "reachability"
	// ExploitabilityConstraint matches when a vulnerability has known
	// exploitation metadata.
	ExploitabilityConstraint FailOnKind = "exploitability"
)

type FallbackDetector 

type FallbackDetector interface {
	FallbackDetector() Detector
}

FallbackDetector optionally provides a fallback detector that should run when the primary detector cannot produce a result.

type Finding 

type Finding struct {
	ID               string             `json:"id"`
	Kind             FindingKind        `json:"kind"`
	Title            string             `json:"title,omitempty"`
	Severity         SeverityLevel      `json:"severity,omitempty"`
	Disposition      FindingDisposition `json:"disposition,omitempty"`
	Reasons          []string           `json:"reasons,omitempty"`
	Source           string             `json:"source,omitempty"`
	Auditor          string             `json:"auditor,omitempty"`
	VexStatus        VEXStatus          `json:"vex_status,omitempty"`
	VEXJustification string             `json:"vex_justification,omitempty"`
	// PackageRef is the PURL of the offending package in the registry.
	PackageRef string `json:"package_ref,omitempty"`
	// DependencyRefs are the dependency node IDs that introduced the package.
	DependencyRefs []string `json:"dependency_refs,omitempty"`
	// VulnerabilityID is the advisory id within the referenced package, set
	// for vulnerability-kind findings.
	VulnerabilityID string `json:"vulnerability_id,omitempty"`
}

Finding describes a normalized audit result as a reference into the package registry rather than an inlined copy of vulnerability data. Consumers resolve the underlying enrichment via PackageRef (PURL) and, for vulnerability findings, VulnerabilityID (the OSV id inside the referenced package).

func (Finding) Clone 

func (f Finding) Clone() Finding

Clone returns a deep copy of the finding.

type FindingDisposition 

type FindingDisposition string

FindingDisposition controls whether a finding should fail policy evaluation or surface as a warning only. 

const (
	FindingDispositionFail FindingDisposition = "fail"
	FindingDispositionWarn FindingDisposition = "warn"
)

type FindingKind 

type FindingKind string

FindingKind categorizes audit findings by the underlying concern the auditor is reporting on. Each built-in auditor emits findings of exactly one kind: 

FindingKindVulnerability — emitted by the vulnerability auditor
FindingKindLicense       — emitted by the license auditor
FindingKindPackage       — emitted by the package auditor

External plugins may introduce new kinds; consumers should treat the list as open. 

const (
	FindingKindVulnerability FindingKind = "vulnerability"
	FindingKindLicense       FindingKind = "license"
	FindingKindPackage       FindingKind = "package"
)

type FixAvailable 

type FixAvailable struct {
	Version string           `json:"version,omitempty"`
	Date    string           `json:"date,omitempty"`
	Kind    FixAvailableKind `json:"kind,omitempty"`
}

FixAvailable captures one version/date/kind tuple for an available fix.

type FixAvailableKind added in v0.13.0 

type FixAvailableKind string

FixAvailableKind identifies why a fix version was selected. 

const (
	FixAvailableFirstObserved FixAvailableKind = "first-observed"
)

type FixState added in v0.13.0 

type FixState string

FixState identifies whether a vulnerability has a known fix. 

const (
	FixStateUnknown  FixState = "unknown"
	FixStateFixed    FixState = "fixed"
	FixStateNotFixed FixState = "not-fixed"
	FixStateWontFix  FixState = "wont-fix"
)

type Graph 

type Graph struct {
	// contains filtered or unexported fields
}

Graph stores dependency nodes as a directed graph.

func ConsolidateGraphContainerEntry 

func ConsolidateGraphContainerEntry(container *GraphContainer) (*Graph, error)

ConsolidateGraphContainerEntry ensures one entry is present.

func FilterGraphByScope 

func FilterGraphByScope(src *Graph, scope Scope) (*Graph, error)

FilterGraphByScope returns a graph view containing roots plus dependencies whose normalized scope matches the requested filter.

func New 

func New() *Graph

New creates an empty dependency graph.

func NewWithCapacity 

func NewWithCapacity(nodeCount int) *Graph

NewWithCapacity creates an empty dependency graph sized for the expected node count.

func (*Graph) AddEdge 

func (g *Graph) AddEdge(fromID, toID string) error

AddEdge adds a dependency relationship fromID -> toID, meaning fromID depends on toID.

func (*Graph) AddNode 

func (g *Graph) AddNode(node *Dependency) error

AddNode inserts a dependency node.

func (*Graph) CollectPathsTo 

func (g *Graph) CollectPathsTo(targetID string) ([]Path, error)

CollectPathsTo returns deterministic root-to-target dependency paths.

func (*Graph) Dependents 

func (g *Graph) Dependents(id string) ([]*Dependency, error)

Dependents returns direct dependents for a node, sorted by ID.

func (*Graph) DirectDependencies 

func (g *Graph) DirectDependencies(id string) ([]*Dependency, error)

DirectDependencies returns direct dependencies for a node, sorted by ID.

func (*Graph) Leaves 

func (g *Graph) Leaves() []*Dependency

Leaves returns nodes with no outgoing relationships.

func (*Graph) MarshalJSON 

func (g *Graph) MarshalJSON() ([]byte, error)

MarshalJSON encodes a graph as a stable transport-friendly adjacency list.

func (*Graph) Node 

func (g *Graph) Node(id string) (*Dependency, bool)

Node returns a dependency node by ID.

func (*Graph) Nodes 

func (g *Graph) Nodes() []*Dependency

Nodes returns all dependency nodes sorted by ID.

func (*Graph) PrettyString 

func (g *Graph) PrettyString() string

PrettyString returns a stable, human-readable adjacency list.

func (*Graph) PrettyTree 

func (g *Graph) PrettyTree() string

PrettyTree returns an ASCII tree view of dependencies from graph roots.

func (*Graph) RemoveEdge 

func (g *Graph) RemoveEdge(fromID, toID string) bool

RemoveEdge removes a dependency relationship and reports whether it existed.

func (*Graph) RemoveNode 

func (g *Graph) RemoveNode(id string) bool

RemoveNode removes a node and all incident relationships.

func (*Graph) Roots 

func (g *Graph) Roots() []*Dependency

Roots returns nodes with no incoming relationships.

func (*Graph) Size 

func (g *Graph) Size() int

Size returns the number of nodes in the graph.

func (*Graph) TopologicalSort 

func (g *Graph) TopologicalSort() ([]*Dependency, error)

TopologicalSort returns a topological ordering for the acyclic portion of the graph. If cycles remain, the returned slice contains the ordered prefix and ErrCycleDetected.

func (*Graph) UnmarshalJSON 

func (g *Graph) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes a graph from the plugin transport adjacency list.

func (*Graph) WalkEdges 

func (g *Graph) WalkEdges(fn func(from, to *Dependency) bool)

WalkEdges iterates all dependency relationships (from -> to). Returning false stops iteration.

func (*Graph) WalkNodes 

func (g *Graph) WalkNodes(fn func(*Dependency) bool)

WalkNodes iterates all live nodes. Returning false from fn stops iteration.

type GraphContainer 

type GraphContainer struct {
	Entries []GraphEntry `json:"entries,omitempty"`
}

GraphContainer groups one or more manifest-scoped dependency graphs.

func SingleGraphContainer 

func SingleGraphContainer(g *Graph, manifest ManifestMetadata) *GraphContainer

SingleGraphContainer wraps a single graph entry.

func (*GraphContainer) ConsolidatedGraph 

func (c *GraphContainer) ConsolidatedGraph() (*Graph, error)

ConsolidatedGraph materializes a single graph view for the container.

func (*GraphContainer) Len 

func (c *GraphContainer) Len() int

Len returns the number of graph entries.

type GraphEntry 

type GraphEntry struct {
	Graph    *Graph           `json:"graph,omitempty"`
	Manifest ManifestMetadata `json:"manifest"`
	Packages []*Package       `json:"packages,omitempty"`
}

GraphEntry describes one manifest-scoped dependency graph. Detection-time package facts discovered alongside the graph (licenses, digests, copyright pulled from lockfiles) are carried in Packages for folding into the global package registry during consolidation.

type HTTPClientConfig 

type HTTPClientConfig struct {
	ProxyURL      string
	NoProxy       string
	ProxyType     string
	ProxyHost     string
	ProxyPort     int
	ProxyUsername string
	ProxyPassword string
	CACertFile    string
	Timeout       time.Duration
}

HTTPClientConfig configures Bomly's shared outbound HTTP client.

func HTTPClientConfigFromEnv 

func HTTPClientConfigFromEnv() HTTPClientConfig

HTTPClientConfigFromEnv returns Bomly-specific HTTP client settings from environment variables. Standard HTTP_PROXY, HTTPS_PROXY, and NO_PROXY are still honored by NewHTTPClient when Bomly-specific values are absent.

func (HTTPClientConfig) EffectiveProxyURL 

func (config HTTPClientConfig) EffectiveProxyURL() (string, error)

EffectiveProxyURL returns the effective proxy URL after applying Bomly's URL or decomposed proxy settings. It does not inspect standard proxy environment variables.

type HTTPClientProvider 

type HTTPClientProvider struct {
	// contains filtered or unexported fields
}

HTTPClientProvider owns reusable HTTP transport state for one Bomly execution.

func NewHTTPClientProvider 

func NewHTTPClientProvider(config HTTPClientConfig) (*HTTPClientProvider, error)

NewHTTPClientProvider creates an HTTP client provider with a reusable transport. Call Client to create timeout-specific clients that share connection pools and TLS/proxy settings.

func NewHTTPClientProviderFromEnv 

func NewHTTPClientProviderFromEnv() (*HTTPClientProvider, error)

NewHTTPClientProviderFromEnv creates a provider from Bomly HTTP environment variables, with standard proxy environment variables honored as fallback.

func (*HTTPClientProvider) Client 

func (p *HTTPClientProvider) Client(timeout time.Duration) *http.Client

Client returns an HTTP client with the requested timeout. A zero timeout uses the provider's configured default timeout.

func (*HTTPClientProvider) CloseIdleConnections 

func (p *HTTPClientProvider) CloseIdleConnections()

CloseIdleConnections closes idle connections held by the provider transport.

type InstallFirstDetector 

type InstallFirstDetector interface {
	Install(context.Context, DetectionRequest) error
}

InstallFirstDetector optionally prepares dependencies before graph resolution.

type InstallResponse 

type InstallResponse struct {
	Performed bool `json:"performed,omitempty"`
}

InstallResponse reports install-first execution details.

type KnownExploited 

type KnownExploited struct {
	CVE                        string   `json:"cve,omitempty"`
	VendorProject              string   `json:"vendor_project,omitempty"`
	Product                    string   `json:"product,omitempty"`
	DateAdded                  string   `json:"date_added,omitempty"`
	RequiredAction             string   `json:"required_action,omitempty"`
	DueDate                    string   `json:"due_date,omitempty"`
	KnownRansomwareCampaignUse string   `json:"known_ransomware_campaign_use,omitempty"`
	Notes                      string   `json:"notes,omitempty"`
	URLs                       []string `json:"urls,omitempty"`
	CWEs                       []string `json:"cwes,omitempty"`
}

KnownExploited captures CISA KEV-style known exploitation metadata.

type Language 

type Language string

Language identifies the programming language used by a package or analyzed by a code analyzer. Languages are coarse-grained and ecosystem-agnostic; one PackageManager can carry multiple languages (e.g. Maven covers Java, Kotlin, Scala, and Groovy). 

const (
	LanguageUnknown    Language = ""
	LanguageGo         Language = "go"
	LanguageJavaScript Language = "javascript"
	LanguageTypeScript Language = "typescript"
	LanguagePython     Language = "python"
	LanguageJava       Language = "java"
	LanguageKotlin     Language = "kotlin"
	LanguageScala      Language = "scala"
	LanguageGroovy     Language = "groovy"
	LanguageRuby       Language = "ruby"
	LanguagePHP        Language = "php"
	LanguageRust       Language = "rust"
	LanguageCSharp     Language = "csharp"
	LanguageFSharp     Language = "fsharp"
	LanguageVB         Language = "vb"
	LanguageSwift      Language = "swift"
	LanguageObjC       Language = "objective-c"
	LanguageDart       Language = "dart"
	LanguageElixir     Language = "elixir"
	LanguageErlang     Language = "erlang"
	LanguageHaskell    Language = "haskell"
	LanguageOCaml      Language = "ocaml"
	LanguageLua        Language = "lua"
	LanguageR          Language = "r"
	LanguageC          Language = "c"
	LanguageCPP        Language = "cpp"
)

func LanguageFromPackage 

func LanguageFromPackage(p Package) Language

LanguageFromPackage returns the most specific language for a package. It prefers the package's own Language field, then falls back to the primary language declared by the package's PackageManager (if recognizable), and finally returns LanguageUnknown.

func ParseLanguage 

func ParseLanguage(value string) Language

ParseLanguage normalizes a string into a Language. Returns LanguageUnknown for unrecognized values; callers that need strict validation should compare the result against LanguageUnknown for non-empty input.

type LicenseType added in v0.13.0 

type LicenseType string

LicenseType identifies license provenance. 

const (
	LicenseTypeDeclared LicenseType = "declared"
)

type ManifestKind 

type ManifestKind string

ManifestKind identifies the manifest family represented by one graph entry. 

const (
	// ManifestKindPackageLockJSON identifies npm package-lock.json manifests.
	ManifestKindPackageLockJSON ManifestKind = "package-lock.json"
	// ManifestKindNPMLockfile identifies generic npm lockfile manifests.
	ManifestKindNPMLockfile ManifestKind = "npm-lockfile"
	// ManifestKindPackageJSON identifies npm package.json manifests.
	ManifestKindPackageJSON ManifestKind = "package.json"
	// ManifestKindGoMod identifies Go module manifests.
	ManifestKindGoMod ManifestKind = "go.mod"
	// ManifestKindGoModule identifies normalized Go module manifests.
	ManifestKindGoModule ManifestKind = "go-module"
	// ManifestKindPomXML identifies Maven POM manifests.
	ManifestKindPomXML ManifestKind = "pom.xml"
	// ManifestKindRequirementsTXT identifies Python requirements manifests.
	ManifestKindRequirementsTXT ManifestKind = "requirements.txt"
	// ManifestKindSPDX identifies SPDX SBOM manifests.
	ManifestKindSPDX ManifestKind = "spdx"
	// ManifestKindSBOM identifies generic SBOM manifests.
	ManifestKindSBOM ManifestKind = "sbom"
	// ManifestKindGitHubSPDX identifies GitHub-produced SPDX SBOM manifests.
	ManifestKindGitHubSPDX ManifestKind = "github.spdx"
	// ManifestKindBomlySPDX identifies Bomly-produced SPDX SBOM manifests.
	ManifestKindBomlySPDX ManifestKind = "bomly.spdx"
	// ManifestKindGitHubActions identifies GitHub Actions manifests.
	ManifestKindGitHubActions ManifestKind = "github-actions"
	// ManifestKindGitHubActionsWorkflow identifies GitHub Actions workflow files.
	ManifestKindGitHubActionsWorkflow ManifestKind = "github-actions-workflow"
	// ManifestKindGitHubActionsAction identifies GitHub Actions action metadata files.
	ManifestKindGitHubActionsAction ManifestKind = "github-actions-action"
)

type ManifestMetadata 

type ManifestMetadata struct {
	Path string       `json:"path,omitempty"`
	Kind ManifestKind `json:"kind,omitempty"`
}

ManifestMetadata describes the manifest or evidence file associated with one graph.

type MatchRequest 

type MatchRequest struct {
	ProjectPath     string           `json:"projectPath,omitempty"`
	ExecutionTarget ExecutionTarget  `json:"executionTarget"`
	SubprojectInfo  Subproject       `json:"subprojectInfo"`
	Ecosystem       Ecosystem        `json:"ecosystem,omitempty"`
	PackageManager  PackageManager   `json:"packageManager,omitempty"`
	Query           PackageQuery     `json:"query"`
	Graph           *Graph           `json:"graph,omitempty"`
	Registry        *PackageRegistry `json:"registry,omitempty"`
	Target          *Dependency      `json:"target,omitempty"`
	MatcherFilter   MatcherFilter    `json:"matcherFilter"`
	Stderr          io.Writer        `json:"-"`
}

MatchRequest defines input for a matcher. Matchers enrich the package Registry keyed by PURL; the dependency Graph provides identity and structure.

type MatchResponse 

type MatchResponse = MatchResult

MatchResponse is the matcher response payload exposed to plugins.

type MatchResult 

type MatchResult struct {
	Registry     *PackageRegistry `json:"registry,omitempty"`
	MatcherStats MatcherStats     `json:"matcherStats,omitempty"`
}

MatchResult contains the package registry after matcher enrichment.

type Matcher 

type Matcher interface {
	Descriptor() MatcherDescriptor
	Ready() bool
	Applicable(context.Context, MatchRequest) (bool, error)
	Match(context.Context, MatchRequest) (MatchResult, error)
}

Matcher enriches registry packages with license and vulnerability data.

type MatcherDescriptor 

type MatcherDescriptor struct {
	Name                string           `json:"name"`
	DisplayName         string           `json:"displayName,omitempty"`
	Aliases             []string         `json:"aliases,omitempty"`
	Tags                []string         `json:"tags,omitempty"`
	SupportedEcosystems []Ecosystem      `json:"supportedEcosystems,omitempty"`
	SupportedManagers   []PackageManager `json:"supportedManagers,omitempty"`
}

MatcherDescriptor describes a matcher registration.

func (MatcherDescriptor) Label 

func (d MatcherDescriptor) Label() string

Label returns the user-facing matcher label, falling back to Name.

type MatcherFilter 

type MatcherFilter struct {
	Include []string
	Exclude []string
}

MatcherFilter narrows matcher selection for a request.

func (MatcherFilter) Excludes 

func (f MatcherFilter) Excludes(name string) bool

Excludes reports whether a matcher name is explicitly denied.

func (MatcherFilter) Includes 

func (f MatcherFilter) Includes(name string) bool

Includes reports whether a matcher name is explicitly allowed.

type MatcherStats 

type MatcherStats struct {
	Name              string `json:"name"`
	DisplayName       string `json:"displayName,omitempty"`
	MatchedPackages   int    `json:"matchedPackages,omitempty"`
	UnmatchedPackages int    `json:"unmatchedPackages,omitempty"`
	Licenses          int    `json:"licenses,omitempty"`
	Vulnerabilities   int    `json:"vulnerabilities,omitempty"`
}

MatcherStats describes one completed matcher run and optional summary counts.

type NPMPackageMetadata 

type NPMPackageMetadata struct {
	Bundled                  bool              `json:"bundled,omitempty"`
	Extraneous               bool              `json:"extraneous,omitempty"`
	HasInstallScript         bool              `json:"hasInstallScript,omitempty"`
	PeerDependencies         map[string]string `json:"peerDependencies,omitempty"`
	OptionalPeerDependencies []string          `json:"optionalPeerDependencies,omitempty"`
	Engines                  map[string]string `json:"engines,omitempty"`
}

NPMPackageMetadata holds npm-specific package data extracted from npm/pnpm/yarn lockfiles that does not fit into the cross-ecosystem fields.

type Package 

type Package struct {
	Coordinates
	// ID is the package registry identifier. It may be a database ID, PURL, or
	// another stable key chosen by the package registry.
	ID          string `json:"id,omitempty"`
	Copyright   string `json:"copyright,omitempty"`
	ResolvedURL string `json:"resolved_url,omitempty"`

	CPEs            []string          `json:"cpes,omitempty"`
	Digests         []Digest          `json:"digests,omitempty"`
	Licenses        []PackageLicense  `json:"licenses,omitempty"`
	Vulnerabilities []Vulnerability   `json:"vulnerabilities,omitempty"`
	Scorecard       *PackageScorecard `json:"scorecard,omitempty"`
	EOL             *PackageEOL       `json:"eol,omitempty"`

	// Matched indicates that this package was successfully matched by one or
	// more external enrichment sources.
	Matched bool `json:"matched,omitempty"`

	// Metadata holds per-ecosystem extensible data.
	Metadata map[string]any `json:"metadata,omitempty"`
}

Package describes one matching artifact: the PURL-keyed, deduplicated record produced by the matching stage. Many Dependency nodes (across manifests and subprojects) reference a single Package by PURL. A Package holds only matching-stage enrichment; detection-time identity and relationships live on Dependency.

func PackageFromDependency 

func PackageFromDependency(dep *Dependency) *Package

PackageFromDependency seeds a registry package from a dependency's identity fields. The returned package carries no enrichment; matchers fill it in.

func (*Package) Clone 

func (p *Package) Clone() *Package

Clone returns a deep copy of the package.

func (*Package) DisplayName 

func (p *Package) DisplayName() string

DisplayName returns the most human-friendly identifier available.

func (*Package) IdentityKey 

func (p *Package) IdentityKey() string

IdentityKey returns a stable package identity without version information.

func (*Package) LicenseValues 

func (p *Package) LicenseValues() []string

LicenseValues returns normalized package license labels in stable order.

func (*Package) MergeFrom 

func (p *Package) MergeFrom(src *Package)

MergeFrom folds enrichment from src into p in place. Used by the package registry to deduplicate multiple records for the same PURL. Existing typed data on p wins; src contributes anything p is missing, and vulnerability lists are unioned by (Source, ID).

func (*Package) QualifiedName 

func (p *Package) QualifiedName() string

QualifiedName returns the package name prefixed with its organization when present.

type PackageEOL 

type PackageEOL struct {
	Source        string `json:"source,omitempty"`
	Cycle         string `json:"cycle,omitempty"`
	EOL           bool   `json:"eol,omitempty"`
	EOLDate       string `json:"eol_date,omitempty"`
	LatestVersion string `json:"latest_version,omitempty"`
	ReleaseDate   string `json:"release_date,omitempty"`
	Supported     bool   `json:"supported,omitempty"`
}

PackageEOL captures end-of-life enrichment attached by the EOL matcher.

func (*PackageEOL) Clone 

func (e *PackageEOL) Clone() *PackageEOL

Clone returns a deep copy of the EOL payload.

type PackageLicense 

type PackageLicense struct {
	Value          string      `json:"value,omitempty"`
	SPDXExpression string      `json:"spdx_expression,omitempty"`
	Type           LicenseType `json:"type,omitempty"`
}

PackageLicense captures normalized license details for a package.

func DetectionLicenses 

func DetectionLicenses(dep *Dependency) []PackageLicense

DetectionLicenses returns license facts stashed on dep at detection time.

type PackageLocation 

type PackageLocation struct {
	RealPath   string `json:"real_path,omitempty"`
	AccessPath string `json:"access_path,omitempty"`
	// Position optionally points at the exact line / column in RealPath where
	// the package is declared. nil when unknown.
	Position *SourcePosition `json:"position,omitempty"`
}

PackageLocation captures where a package was discovered.

type PackageManager 

type PackageManager string

PackageManager identifies the concrete package manager or manifest family for a target. 

const (
	PackageManagerUnknown       PackageManager = ""
	PackageManagerNPM           PackageManager = "npm"
	PackageManagerPNPM          PackageManager = "pnpm"
	PackageManagerYarn          PackageManager = "yarn"
	PackageManagerGradle        PackageManager = "gradle"
	PackageManagerMaven         PackageManager = "maven"
	PackageManagerGoMod         PackageManager = "gomod"
	PackageManagerPip           PackageManager = "pip"
	PackageManagerPipenv        PackageManager = "pipenv"
	PackageManagerPoetry        PackageManager = "poetry"
	PackageManagerUV            PackageManager = "uv"
	PackageManagerALPM          PackageManager = "alpm"
	PackageManagerAPK           PackageManager = "apk"
	PackageManagerConan         PackageManager = "conan"
	PackageManagerConda         PackageManager = "conda"
	PackageManagerPub           PackageManager = "pub"
	PackageManagerDPKG          PackageManager = "dpkg"
	PackageManagerMix           PackageManager = "mix"
	PackageManagerRebar         PackageManager = "rebar"
	PackageManagerOTP           PackageManager = "otp"
	PackageManagerGitHubActions PackageManager = "github-actions"
	PackageManagerCabal         PackageManager = "cabal"
	PackageManagerStack         PackageManager = "stack"
	PackageManagerHomebrew      PackageManager = "homebrew"
	PackageManagerLuaRocks      PackageManager = "luarocks"
	PackageManagerNuGet         PackageManager = "nuget"
	PackageManagerNix           PackageManager = "nix"
	PackageManagerOpam          PackageManager = "opam"
	PackageManagerComposer      PackageManager = "composer"
	PackageManagerPear          PackageManager = "pear"
	PackageManagerPDM           PackageManager = "pdm"
	PackageManagerPortage       PackageManager = "portage"
	PackageManagerSWIPLPack     PackageManager = "swipl-pack"
	PackageManagerRPackage      PackageManager = "r-package"
	PackageManagerRPM           PackageManager = "rpm"
	PackageManagerBundler       PackageManager = "bundler"
	PackageManagerGemspec       PackageManager = "gemspec"
	PackageManagerCargo         PackageManager = "cargo"
	PackageManagerSBOM          PackageManager = "sbom"
	PackageManagerSnap          PackageManager = "snap"
	PackageManagerCocoaPods     PackageManager = "cocoapods"
	PackageManagerSwiftPM       PackageManager = "swiftpm"
	PackageManagerTerraform     PackageManager = "terraform"
	PackageManagerWordPress     PackageManager = "wordpress"
	PackageManagerSetupPy       PackageManager = "setuppy"
	PackageManagerOther         PackageManager = "other"
	PackageManagerSBT           PackageManager = "sbt"
	PackageManagerMultiple      PackageManager = "multiple"
)

func AllPackageManagers 

func AllPackageManagers() []PackageManager

AllPackageManagers returns the canonical package-manager list in SDK order.

func ParsePackageManager 

func ParsePackageManager(value string) (PackageManager, error)

ParsePackageManager normalizes a package-manager value.

func (PackageManager) Ecosystem 

func (p PackageManager) Ecosystem() Ecosystem

Ecosystem returns the higher-level grouping for a package manager.

func (PackageManager) Languages 

func (p PackageManager) Languages() []Language

Languages returns the programming languages typically built with this package manager. The first entry is the most common / canonical language; callers that need a single value should take Languages()[0]. Returns nil for OS-level managers and any manager that does not have a meaningful language association.

func (PackageManager) MarshalJSON 

func (p PackageManager) MarshalJSON() ([]byte, error)

MarshalJSON encodes a package manager by its canonical name.

func (PackageManager) Name 

func (p PackageManager) Name() string

Name returns the canonical package-manager name.

func (PackageManager) String 

func (p PackageManager) String() string

String returns the canonical package-manager name.

func (*PackageManager) UnmarshalJSON 

func (p *PackageManager) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes a package manager from its canonical name.

type PackageManagerSupport 

type PackageManagerSupport struct {
	PackageManager   PackageManager `json:"packageManager"`
	EvidencePatterns []string       `json:"evidencePatterns,omitempty"`
}

PackageManagerSupport records package-manager discovery metadata for a detector.

func Support 

func Support(manager PackageManager, evidencePatterns ...string) PackageManagerSupport

Support returns package-manager discovery metadata for a detector.

type PackageManagerSupporter 

type PackageManagerSupporter interface {
	PackageManagerSupport() []PackageManagerSupport
}

PackageManagerSupporter reports detector package-manager discovery metadata.

type PackageQuery 

type PackageQuery struct {
	Name string `json:"name,omitempty"`
	ID   string `json:"id,omitempty"`
}

PackageQuery identifies a specific package target.

type PackageRegistry 

type PackageRegistry struct {
	// contains filtered or unexported fields
}

PackageRegistry is the PURL-keyed, deduplicated set of matching artifacts produced by the matching stage. Detection produces Dependency nodes that reference packages here by PURL; matchers enrich the packages once per PURL regardless of how many dependency instances point at them.

func NewPackageRegistry 

func NewPackageRegistry() *PackageRegistry

NewPackageRegistry creates an empty registry.

func (*PackageRegistry) Add 

func (r *PackageRegistry) Add(pkg *Package) *Package

Add inserts pkg, merging into any existing record with the same PURL, and returns the canonical stored package. Packages without a PURL are ignored.

func (*PackageRegistry) All 

func (r *PackageRegistry) All() []*Package

All returns every package sorted by PURL.

func (*PackageRegistry) Ensure 

func (r *PackageRegistry) Ensure(purl string) *Package

Ensure returns the registry package for purl, creating an empty one when absent. Returns nil for an empty purl.

func (*PackageRegistry) Get 

func (r *PackageRegistry) Get(purl string) (*Package, bool)

Get returns the package for purl, if present.

func (*PackageRegistry) Len 

func (r *PackageRegistry) Len() int

Len returns the number of packages in the registry.

func (*PackageRegistry) MarshalJSON 

func (r *PackageRegistry) MarshalJSON() ([]byte, error)

MarshalJSON encodes a package registry as a stable PURL-keyed object for plugin transport.

func (*PackageRegistry) Merge 

func (r *PackageRegistry) Merge(other *PackageRegistry)

Merge folds every package from other into r.

func (*PackageRegistry) UnmarshalJSON 

func (r *PackageRegistry) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes a PURL-keyed package registry from plugin transport.

type PackageScorecard 

type PackageScorecard struct {
	// Source identifies where the data came from (e.g. "api.scorecard.dev").
	Source string `json:"source,omitempty"`
	// Repository is the canonical repo identifier scored, e.g.
	// "github.com/kubernetes/kubernetes".
	Repository string `json:"repository,omitempty"`
	// CommitSHA is the repo commit the run scored.
	CommitSHA string `json:"commitSha,omitempty"`
	// ScorecardVersion is the version of the Scorecard tool that produced
	// the run.
	ScorecardVersion string `json:"scorecardVersion,omitempty"`
	// RunDate is when the run was performed.
	RunDate time.Time `json:"runDate,omitempty"`
	// AggregateScore is the overall Scorecard aggregate, 0.0–10.0.
	// A negative value (typically -1) indicates "unscored".
	AggregateScore float64 `json:"aggregateScore"`
	// Checks holds per-check results in the order returned by Scorecard.
	Checks []PackageScorecardCheck `json:"checks,omitempty"`
}

PackageScorecard holds the latest OpenSSF Scorecard run attached to a package by the scorecard matcher. A nil value means no run was attached (no resolvable source repo, the OSSF has not scored the project, or the matcher was not selected).

func (*PackageScorecard) Clone 

func (s *PackageScorecard) Clone() *PackageScorecard

Clone returns a deep copy of the scorecard payload, including its checks.

type PackageScorecardCheck 

type PackageScorecardCheck struct {
	// Name is the Scorecard check name, e.g. "Branch-Protection".
	Name string `json:"name"`
	// Score is 0–10, or -1 when the check is inconclusive.
	Score int `json:"score"`
	// Reason is the short summary Scorecard emits for the check.
	Reason string `json:"reason,omitempty"`
	// Documentation links to the canonical documentation page for the check.
	Documentation string `json:"documentation,omitempty"`
}

PackageScorecardCheck describes a single Scorecard check result.

type PackageType added in v0.13.0 

type PackageType string

PackageType describes the broad role or artifact kind of a package node. 

const (
	PackageTypeUnknown     PackageType = ""
	PackageTypeApplication PackageType = "application"
	PackageTypePackage     PackageType = "package"
	PackageTypeManifest    PackageType = "manifest"
	PackageTypeWorkflow    PackageType = "workflow"
	PackageTypeAction      PackageType = "action"
	PackageTypeTransitive  PackageType = "transitive"
	PackageTypeProject     PackageType = "project"
	PackageTypeFile        PackageType = "file"
)

func ParsePackageType added in v0.13.0 

func ParsePackageType(value string) PackageType

ParsePackageType normalizes a package role string.

func (PackageType) String added in v0.13.0 

func (t PackageType) String() string

String returns the package type value.

type Path 

type Path struct {
	Nodes   []*Dependency
	Cyclic  bool
	CycleTo string
}

Path describes one dependency path through the graph.

type PluginKind 

type PluginKind string

PluginKind identifies the runtime role implemented by a plugin. 

const (
	// PluginKindDetector resolves dependency graphs.
	PluginKindDetector PluginKind = "detector"
	// PluginKindMatcher enriches resolved packages.
	PluginKindMatcher PluginKind = "matcher"
	// PluginKindAuditor evaluates findings and risk.
	PluginKindAuditor PluginKind = "auditor"
	// PluginKindAnalyzer runs code analysis (e.g. reachability) over the
	// matched graph and annotates registry vulnerability entries.
	PluginKindAnalyzer PluginKind = "analyzer"
)

type PluginTargetType 

type PluginTargetType string

PluginTargetType identifies the discovery target families a plugin supports.

type RangeEvent 

type RangeEvent struct {
	Introduced   string `json:"introduced,omitempty"`
	Fixed        string `json:"fixed,omitempty"`
	LastAffected string `json:"last_affected,omitempty"`
	Limit        string `json:"limit,omitempty"`
}

RangeEvent is one OSV range event marker.

type Reachability 

type Reachability struct {
	Status                 ReachabilityStatus     `json:"status"`
	Tier                   ReachabilityTier       `json:"tier,omitempty"`
	Analyzer               string                 `json:"analyzer,omitempty"`
	Reason                 string                 `json:"reason,omitempty"`
	Symbols                []AffectedSymbol       `json:"symbols,omitempty"`
	CallPaths              []CallPath             `json:"call_paths,omitempty"`
	Hops                   *int                   `json:"hops,omitempty"`
	Confidence             ReachabilityConfidence `json:"confidence,omitempty"`
	DynamicImportsDetected bool                   `json:"dynamic_imports_detected,omitempty"`
	AnalyzedAt             string                 `json:"analyzed_at,omitempty"`
}

Reachability is the analyzer-supplied reachability annotation for one vulnerability. Stored on Vulnerability.

func (*Reachability) Clone 

func (r *Reachability) Clone() *Reachability

Clone returns a deep copy of the reachability annotation.

type ReachabilityConfidence 

type ReachabilityConfidence string

ReachabilityConfidence is a coarse triage signal derived from Hops and DynamicImportsDetected. 

const (
	ConfidenceUnknown ReachabilityConfidence = ""
	ConfidenceHigh    ReachabilityConfidence = "high"
	ConfidenceMedium  ReachabilityConfidence = "medium"
	ConfidenceLow     ReachabilityConfidence = "low"
)

func DeriveConfidence 

func DeriveConfidence(hops *int, dynamicImports bool) ReachabilityConfidence

DeriveConfidence computes a confidence label from a hop count and a dynamic-imports flag. Returns ConfidenceUnknown when hops is nil.

type ReachabilityStats 

type ReachabilityStats struct {
	Reachable     int `json:"reachable,omitempty"`
	Unreachable   int `json:"unreachable,omitempty"`
	Unknown       int `json:"unknown,omitempty"`
	NotApplicable int `json:"not_applicable,omitempty"`
}

ReachabilityStats tallies the per-analyzer outcome distribution.

type ReachabilityStatus 

type ReachabilityStatus string

ReachabilityStatus is the outcome of a reachability analysis for one vulnerability. 

const (
	ReachabilityUnknown     ReachabilityStatus = "unknown"
	ReachabilityReachable   ReachabilityStatus = "reachable"
	ReachabilityUnreachable ReachabilityStatus = "unreachable"
)

type ReachabilityTier 

type ReachabilityTier string

ReachabilityTier communicates the precision of a reachability result. 

const (
	TierSymbol  ReachabilityTier = "symbol"
	TierPackage ReachabilityTier = "package"
	TierNone    ReachabilityTier = "none"
)

type ReadyResponse 

type ReadyResponse struct {
	Ready bool `json:"ready"`
}

ReadyResponse reports whether a plugin is ready to run.

type Reference 

type Reference struct {
	URL  string        `json:"url,omitempty"`
	Type ReferenceType `json:"type,omitempty"`
}

Reference is a URL and type pair.

type ReferenceType added in v0.13.0 

type ReferenceType string

ReferenceType identifies the role of a vulnerability reference URL. 

const (
	ReferenceTypeAdvisory   ReferenceType = "advisory"
	ReferenceTypeDataSource ReferenceType = "data_source"
)

type RiskBand added in v0.13.0 

type RiskBand string

RiskBand is the normalized label for a risk score range. 

const (
	RiskBandUnknown  RiskBand = "unknown"
	RiskBandLow      RiskBand = "low"
	RiskBandMedium   RiskBand = "medium"
	RiskBandHigh     RiskBand = "high"
	RiskBandCritical RiskBand = "critical"
)

type RiskScore 

type RiskScore struct {
	PackageRef string         `json:"package_ref,omitempty"`
	Score      int            `json:"score"`
	Band       RiskBand       `json:"band,omitempty"`
	Signals    map[string]any `json:"signals,omitempty"`
}

RiskScore describes a normalized risk result for one package, referenced by its PURL in the package registry.

type Scope 

type Scope string

Scope describes the normalized dependency scope surfaced to users. 

const (
	// ScopeUnknown indicates that a detector could not determine dependency scope.
	ScopeUnknown Scope = ""
	// ScopeRuntime indicates a dependency required at runtime.
	ScopeRuntime Scope = "runtime"
	// ScopeDevelopment indicates a dependency used only for development workflows.
	ScopeDevelopment Scope = "development"
)

func MergeScope 

func MergeScope(current, next Scope) Scope

MergeScope combines two normalized scopes, preferring runtime when a package is reachable from both runtime and development roots.

func ParseScope 

func ParseScope(value string) (Scope, error)

ParseScope normalizes a user-provided dependency scope value.

func ScopesOf 

func ScopesOf(scopes ...Scope) []Scope

ScopesOf returns a one-element scope slice for a non-unknown scope, or nil. Convenience for detectors building Dependency literals from a single scope.

type ServedAuditor 

type ServedAuditor interface {
	Descriptor(context.Context) (*AuditorDescriptor, error)
	Ready(context.Context, *AuditRequest) (*ReadyResponse, error)
	Applicable(context.Context, *AuditRequest) (*ApplicableResponse, error)
	Audit(context.Context, *AuditRequest) (*AuditResponse, error)
}

ServedAuditor is the auditor interface exposed to external plugin authors.

type ServedDetector 

type ServedDetector interface {
	Descriptor(context.Context) (*DetectorDescriptor, error)
	PackageManagerSupport(context.Context) ([]PackageManagerSupport, error)
	Ready(context.Context, *DetectRequest) (*ReadyResponse, error)
	Applicable(context.Context, *DetectRequest) (*ApplicableResponse, error)
	Detect(context.Context, *DetectRequest) (*DetectResponse, error)
}

ServedDetector is the detector interface exposed to external plugin authors.

type ServedMatcher 

type ServedMatcher interface {
	Descriptor(context.Context) (*MatcherDescriptor, error)
	Ready(context.Context, *MatchRequest) (*ReadyResponse, error)
	Applicable(context.Context, *MatchRequest) (*ApplicableResponse, error)
	Match(context.Context, *MatchRequest) (*MatchResponse, error)
}

ServedMatcher is the matcher interface exposed to external plugin authors.

type Severity 

type Severity struct {
	// Type is the OSV severity type, e.g. "CVSS_V3", "CVSS_V4".
	Type SeverityType `json:"type,omitempty"`
	// Score is the vector string or numeric score for Type.
	Score string `json:"score,omitempty"`
}

Severity is one OSV-format severity entry (a CVSS type + vector/score).

type SeverityLevel added in v0.13.0 

type SeverityLevel string

SeverityLevel is Bomly's normalized severity band. 

const (
	// SeverityUnknown indicates that no severity could be determined.
	SeverityUnknown SeverityLevel = "unknown"
	// SeverityNA indicates that severity does not apply to the finding kind.
	SeverityNA SeverityLevel = "n/a"
	// SeverityLow indicates a low-severity issue.
	SeverityLow SeverityLevel = "low"
	// SeverityMedium indicates a medium-severity issue.
	SeverityMedium SeverityLevel = "medium"
	// SeverityHigh indicates a high-severity issue.
	SeverityHigh SeverityLevel = "high"
	// SeverityCritical indicates a critical-severity issue.
	SeverityCritical SeverityLevel = "critical"
	// SeverityAny is a policy threshold that matches every severity.
	SeverityAny SeverityLevel = "any"
)

func ParseSeverityLevel added in v0.13.0 

func ParseSeverityLevel(value string) SeverityLevel

ParseSeverityLevel normalizes a severity string into a SeverityLevel.

type SeverityType added in v0.13.0 

type SeverityType string

SeverityType identifies the OSV severity vector family. 

const (
	SeverityTypeCVSSV2  SeverityType = "CVSS_V2"
	SeverityTypeCVSSV3  SeverityType = "CVSS_V3"
	SeverityTypeCVSSV31 SeverityType = "CVSS_V31"
	SeverityTypeCVSSV4  SeverityType = "CVSS_V4"
)

type SourcePosition 

type SourcePosition struct {
	File    string `json:"file,omitempty"`
	Line    int    `json:"line,omitempty"`
	Column  int    `json:"column,omitempty"`
	EndLine int    `json:"end_line,omitempty"`
}

SourcePosition is the canonical (file, line, column) tuple used wherever the SDK needs to point at a source location. Used by call frames, affected symbols, and (additively) by PackageLocation for declaration sites.

All fields are optional; consumers should treat zero/empty values as "unknown" rather than as positions at line 0 / column 0.

func (SourcePosition) IsZero 

func (p SourcePosition) IsZero() bool

IsZero reports whether the position carries no useful location data.

type Subproject 

type Subproject struct {
	ExecutionTarget         ExecutionTarget  `json:"executionTarget"`
	RelativePath            string           `json:"relativePath,omitempty"`
	PrimaryDetector         string           `json:"primaryDetector,omitempty"`
	DetectedPackageManagers []PackageManager `json:"detectedPackageManagers,omitempty"`
	PlannedDetectors        []string         `json:"plannedDetectors,omitempty"`
	Ecosystem               Ecosystem        `json:"ecosystem,omitempty"`
}

Subproject identifies one package-manager root discovered beneath the execution target.

func (Subproject) PrimaryPackageManager 

func (s Subproject) PrimaryPackageManager() PackageManager

PrimaryPackageManager returns the first entry in DetectedPackageManagers, or PackageManagerUnknown if the list is empty.

type SymbolKind added in v0.13.0 

type SymbolKind string

SymbolKind identifies a vulnerable or reachable code symbol kind. 

const (
	SymbolKindFunction SymbolKind = "function"
	SymbolKindMethod   SymbolKind = "method"
)

type VEXStatus added in v0.13.0 

type VEXStatus string

VEXStatus identifies a finding's VEX disposition. 

const (
	VEXStatusAffected           VEXStatus = "affected"
	VEXStatusNotAffected        VEXStatus = "not_affected"
	VEXStatusFixed              VEXStatus = "fixed"
	VEXStatusUnderInvestigation VEXStatus = "under_investigation"
)

type VersionChange 

type VersionChange struct {
	Before *Dependency
	After  *Dependency
}

VersionChange captures a dependency identity that changed versions.

type VersionRange 

type VersionRange struct {
	// Type is the OSV range type: "SEMVER", "ECOSYSTEM", or "GIT".
	Type   VersionRangeType `json:"type,omitempty"`
	Repo   string           `json:"repo,omitempty"`
	Events []RangeEvent     `json:"events,omitempty"`
}

VersionRange is one OSV affected version range.

type VersionRangeType added in v0.13.0 

type VersionRangeType string

VersionRangeType identifies the OSV affected range scheme. 

const (
	VersionRangeTypeSemver    VersionRangeType = "SEMVER"
	VersionRangeTypeEcosystem VersionRangeType = "ECOSYSTEM"
	VersionRangeTypeGit       VersionRangeType = "GIT"
)

type Vulnerability 

type Vulnerability struct {
	// --- OSV-aligned core ---
	ID               string         `json:"id"`
	Aliases          []string       `json:"aliases,omitempty"`
	Related          []string       `json:"related,omitempty"`
	Summary          string         `json:"summary,omitempty"`
	Details          string         `json:"details,omitempty"`
	Severity         []Severity     `json:"severity,omitempty"`
	Affected         []Affected     `json:"affected,omitempty"`
	References       []Reference    `json:"references,omitempty"`
	Published        string         `json:"published,omitempty"`
	Modified         string         `json:"modified,omitempty"`
	Withdrawn        string         `json:"withdrawn,omitempty"`
	DatabaseSpecific map[string]any `json:"database_specific,omitempty"`

	// --- Bomly enrichment extensions ---
	Source               string           `json:"source,omitempty"`
	DataSource           string           `json:"data_source,omitempty"`
	Namespace            string           `json:"namespace,omitempty"`
	Title                string           `json:"title,omitempty"`
	Reasons              []string         `json:"reasons,omitempty"`
	ParsedSeverity       SeverityLevel    `json:"parsed_severity,omitempty"`
	SeveritySource       string           `json:"severity_source,omitempty"`
	CVSS                 []CVSSScore      `json:"cvss,omitempty"`
	EPSS                 []EPSSScore      `json:"epss,omitempty"`
	CWEs                 []CWE            `json:"cwes,omitempty"`
	KEVExploited         bool             `json:"kev_exploited,omitempty"`
	KnownExploited       []KnownExploited `json:"known_exploited,omitempty"`
	RiskScore            float64          `json:"risk_score,omitempty"`
	FixState             FixState         `json:"fix_state,omitempty"`
	FixedIn              string           `json:"fixed_in,omitempty"`
	FixedVersions        []string         `json:"fixed_versions,omitempty"`
	FixAvailable         []FixAvailable   `json:"fix_available,omitempty"`
	AffectedVersionRange string           `json:"affected_version_range,omitempty"`
	CPEs                 []string         `json:"cpes,omitempty"`
	AffectedSymbols      []AffectedSymbol `json:"affected_symbols,omitempty"`
	Reachability         *Reachability    `json:"reachability,omitempty"`
}

Vulnerability describes a single advisory in an OSV-aligned shape, extended with Bomly-specific enrichment that the OSV schema does not model directly.

The leading block mirrors the OSV (Open Source Vulnerabilities) schema so the records can be exported as OSV with minimal translation. The trailing block carries Bomly enrichment (parsed severity, EPSS, KEV, CWE, risk, fix-state, reachability) attached by matchers and analyzers.

func (Vulnerability) Clone 

func (v Vulnerability) Clone() Vulnerability

Clone returns a deep copy of the vulnerability.

func (Vulnerability) IsExploitable 

func (v Vulnerability) IsExploitable() bool

IsExploitable reports whether advisory metadata says this vulnerability is known exploitable.

func (Vulnerability) MatchesConstraints 

func (v Vulnerability) MatchesConstraints(constraints []FailOnConstraint) bool

MatchesConstraints evaluates one vulnerability against a set of constraints (AND semantics). When constraints is empty, every vulnerability matches (the historical behavior of `--audit` without `--fail-on`).

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.