sdk

package module
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Aug 12, 2026 License: Apache-2.0 Imports: 29 Imported by: 0

README

Bomly SDK

github.com/bomly-dev/bomly-sdk is the contract module for building Bomly components: detectors, matchers, auditors, and analyzers. It contains the neutral domain types (dependencies, packages, vulnerabilities, findings, the package registry), the component interfaces, and the managed-plugin serving adapters and gRPC protocol used by external plugin binaries.

go get github.com/bomly-dev/bomly-sdk@latest

Building a plugin

A Bomly plugin is a standalone Go binary that imports this module and serves one component over the managed-plugin runtime:

package main

import sdk "github.com/bomly-dev/bomly-sdk"

func main() {
	sdk.ServeDetector(myDetector{})
}

See the Bomly plugin documentation for the full authoring guide, packaging layout (bomly-plugin.json), and installation flow.

Embed the Base* types (sdk.BaseDetector, sdk.BaseMatcher, sdk.BaseAuditor, sdk.BaseAnalyzer) in your implementation so future additions to the component interfaces do not break your build.

Helper packages

The SDK ships shared helper subpackages so component modules and external plugins reuse the same implementations Bomly's built-ins use:

  • system — bounded filesystem reads plus exec, path, and environment wrappers.
  • filecache — TTL-based on-disk JSON cache with typed Get/Set helpers.
  • logkit — secret-safe subprocess logging: argument/URL sanitizers, command fields, stderr counter.
  • detectorkit — detector helpers: manifest metadata, source positions, remediation hints, subgraphs, build-tool readiness and timeouts.
  • matcherkit — matcher helpers: registry package seeding and license normalization.
  • testkit — test helpers: fuzz graph invariants, Go binary builders, lockfile position assertions.

Compatibility

Two independent compatibility axes govern this module:

  1. In-process (Go API) — the component interfaces and types consumed by embedders. Signature changes require a recompile. Embedding the Base* defaults insulates implementations from most interface growth.
  2. Wire (managed-plugin protocol bomly.plugin.v1) — JSON payloads exchanged with external plugin binaries. Within protocol v1, changes are strictly additive: new optional (omitempty) fields and new optional RPCs only. Hosts treat unimplemented RPCs as feature fall-backs; unknown JSON fields are ignored by both sides. Fields and RPCs are never removed, renamed, or repurposed within v1. A breaking wire change would ship as a new bomly.plugin.v2 service negotiated alongside v1 — old binaries keep speaking v1.

Plugin binaries built against an older SDK release keep working against newer hosts (and vice versa) as long as both speak protocol v1.

Versioning and releases

Releases are plain semver tags (vX.Y.Z) cut from main. While the module is v0, minor releases may adjust the in-process Go API (the wire contract stays additive regardless); patch releases are always safe. Consumers — Bomly itself and plugin repositories — should pin released versions, never commits or branches.

Release ordering when the contract changes: this module tags first, plugin repositories adopt the new tag, then Bomly updates its pin.

License

Apache-2.0. See LICENSE.

Documentation

Overview

Package sdk is Bomly's public Go contract for dependency graphs, package enrichment, policy findings, and managed external plugins.

Most external developers use this package to build a managed plugin. Managed plugins are native Go binaries that Bomly launches as separate subprocesses over the HashiCorp go-plugin gRPC transport. A plugin implements exactly one externally supported role:

  • detector: reads project evidence and returns dependency graphs
  • matcher: enriches PURL-keyed package records with vulnerability, license, lifecycle, or other package metadata
  • auditor: evaluates graph and registry data and emits findings or risk scores
  • analyzer: runs code analysis (e.g. reachability) over the matched graph and annotates registry vulnerability entries

A plugin binary serves its role from main by calling one of the runtime entrypoints: 

func main() {
	sdk.ServeDetector(&detector{})
}

The corresponding plugin-facing interfaces are ServedDetector, ServedMatcher, ServedAuditor, and ServedAnalyzer. They use the same request and response types as Bomly core: DetectionRequest and DetectionResult for detectors, MatchRequest and MatchResult for matchers, AuditRequest and AuditResult for auditors, and AnalyzeRequest and AnalyzeResult for analyzers.

The central data model deliberately separates pipeline stages. Dependency is a detection-time graph node with identity, locations, scopes, and edges. PackageRegistry is a PURL-keyed set of deduplicated Package records that matchers enrich once per package version. Vulnerability records are OSV-aligned package enrichment data, including Bomly fields such as CVSS, EPSS, KEV, fixed versions, affected symbols, and reachability. Finding is a reference-style audit result: it points back to packages by PURL and, for vulnerability findings, to Vulnerability.ID rather than copying the whole package or advisory payload.

Coordinates is the shared embedded identity shape used by Dependency and Package. Plugin authors should prefer canonical PURLs, fill Coordinates where possible, and use typed values such as Ecosystem, PackageManager, PackageType, Scope, and SeverityLevel instead of raw strings. PackageManager is string-backed for compatibility; use PackageManagerOther or a custom PackageManager value when Bomly does not yet have a first-class constant for a package manager.

Plugin identity is split across package metadata and runtime metadata. The bomly-plugin.json manifest describes packaging and install fields such as ID, version, kind, runtime, plugin API version, entrypoint, homepage, and license. The runtime descriptor returned by Descriptor describes the served component: name, display name, aliases, tags, supported ecosystems, supported package managers, and role-specific behavior. Bomly verifies that manifest identity and runtime descriptor identity match when a packaged plugin is installed, and records installed trust state separately.

Plugins that need configuration should read only their per-plugin config with DecodePluginConfigFromEnv. Plugins that make HTTP calls should create a process-local provider with NewHTTPClientProviderFromEnv so Bomly's proxy, no-proxy, and CA certificate settings are honored consistently.

The repository documentation contains the workflow-oriented guides for packaging, installing, testing, and distributing plugins. This package documentation is the API-oriented reference for the types those guides use.

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 CapabilityPackageUpdates = "package-updates-v1"

CapabilityPackageUpdates is advertised in a matcher's or analyzer's descriptor Capabilities to signal that it can return MatchResult.PackageUpdates / AnalyzeResult.PackageUpdates deltas when the request sets AcceptPackageUpdates. Hosts and plugins that do not know this capability keep exchanging full registries — the protocol v1 baseline.

View Source 
const EnvVerbosity = "BOMLY_VERBOSE"

EnvVerbosity mirrors the host's verbosity environment variable (0 = normal, 1 = verbose, 2+ = debug). Managed components derive their stderr log level from it when present.

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.

View Source 
const (
	SourceChangeValue = "source-change"
)

SourceChangeValue is the supported dependency source-change constraint.

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 ConfigSchemaFor 

func ConfigSchemaFor(prototype any) (json.RawMessage, error)

ConfigSchemaFor derives a JSON Schema (draft 2020-12 subset) for a component's configuration block from a prototype struct. Declare your configuration once as a typed Go struct, decode it at runtime with DecodePluginConfigFromEnv, and advertise its shape in the descriptor: 

type Config struct {
	Endpoint string `json:"endpoint" doc:"API endpoint override" default:"https://api.example.com"`
	Timeout  int    `json:"timeoutSeconds" doc:"Request timeout in seconds" default:"30"`
	Strict   bool   `json:"strict" doc:"Fail on partial results"`
}

descriptor.ConfigSchema = sdk.MustConfigSchemaFor(Config{})

Recognized struct tags: `json` (property name and omission), `doc` (property description), and `default` (default value, converted to the field's type). Nested structs, pointers, slices, and string-keyed maps are supported. Unexported fields and fields tagged `json:"-"` are skipped.

func DecodePluginConfigFromEnv 

func DecodePluginConfigFromEnv(target any) error

DecodePluginConfigFromEnv decodes the current plugin's JSON config file into target. Bomly writes this file from the enabled plugin's own plugins.<plugin-id> config block and exposes its path through the plugin environment.

func FindingPolicyStatusRank 

func FindingPolicyStatusRank(status FindingPolicyStatus) (int, bool)

FindingPolicyStatusRank returns the enforcement rank for a finding policy status. An omitted status retains the historical fail behavior. The boolean is false for unknown values.

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 MustConfigSchemaFor 

func MustConfigSchemaFor(prototype any) json.RawMessage

MustConfigSchemaFor is ConfigSchemaFor that panics on error. Use it for static descriptor initialization where the prototype is a compile-time constant shape.

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 NodeIsEnrichable 

func NodeIsEnrichable(node *Dependency) bool

NodeIsEnrichable reports whether node should be queried against external enrichment sources (advisory databases, package registries, scorecards). Manifest-typed structural nodes and first-party artifacts (workspace members, reactor modules, the project's own package — marked FirstParty by the detector that synthesized them) are not published to public sources, so querying them wastes lookups and risks coincidental name matches; they remain in the packages inventory and in generated SBOMs, just without external enrichment. Ownership is the FirstParty marker, never the package type: an application-typed component imported from an SBOM is an artifact kind, not proof it belongs to the scanned project, and stays enrichable. External plugin matchers should apply the same predicate to the nodes they iterate.

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.

The explicit switch below is the authority: it is consulted for every value before the loose fallback runs, so the most specific mapping wins regardless of the order the caller passes ecosystem / package manager / package type in. The fallback then returns the first non-empty value verbatim, which is only correct where the Bomly identifier happens to be the purl type as well (npm, maven, apk, rpm, ...). Any ecosystem whose purl type differs from its Bomly name needs an explicit case here — without one we emit a type that is not in the purl spec, and consumers keyed on the type (OSV, SBOM ingest) silently fail to match. See issue #317.

Ecosystems that span more than one registry are the exception: erlang covers both Hex (rebar) and OTP (*.app), so it is mapped at the package-manager level only. A bare erlang value with no manager to disambiguate keeps the non-spec pkg:erlang rather than guessing a registry the package may not be published to.

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 ServeAnalyzer 

func ServeAnalyzer(analyzer ServedAnalyzer)

ServeAnalyzer serves one analyzer plugin over Bomly's managed HashiCorp go-plugin gRPC transport. Call it from the plugin binary's main function.

func ServeAuditor 

func ServeAuditor(auditor ServedAuditor)

ServeAuditor serves one auditor plugin over Bomly's managed HashiCorp go-plugin gRPC transport. Call it from the plugin binary's main function.

func ServeDetector 

func ServeDetector(detector ServedDetector)

ServeDetector serves one detector plugin over Bomly's managed HashiCorp go-plugin gRPC transport. Call it from the plugin binary's main function.

func ServeMatcher 

func ServeMatcher(matcher ServedMatcher)

ServeMatcher serves one matcher plugin over Bomly's managed HashiCorp go-plugin gRPC transport. Call it from the plugin binary's main function.

func ServeModule added in v0.2.0 

func ServeModule(m Module)

ServeModule serves one Module as a managed plugin over Bomly's HashiCorp go-plugin gRPC transport. Call it from the plugin binary's main function. It validates the module, builds a managed HostContext (stderr logger, HTTP client provider from Bomly environment variables, config decoding from the file named by BOMLY_PLUGIN_CONFIG_FILE), constructs the component lazily on first use, and adapts it to the served plugin protocol.

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". The GitHub-aligned levels share the ladder with the CVSS bands: error ≡ high, warning ≡ medium, note ≡ low.

func SortDependencyDetailTransitions 

func SortDependencyDetailTransitions(transitions []DependencyDetailTransition)

SortDependencyDetailTransitions orders detail changes deterministically.

func ValidateAnalyzerDescriptor 

func ValidateAnalyzerDescriptor(descriptor *AnalyzerDescriptor) error

ValidateAnalyzerDescriptor validates typed analyzer registration data.

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.

func ValidateModule added in v0.2.0 

func ValidateModule(m Module) error

ValidateModule checks that exactly one role is set, that the role matches the declared Kind, that the role constructor is present, and that the role descriptor validates.

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"`
	// AcceptPackageUpdates signals that the host understands
	// AnalyzeResult.PackageUpdates. Analyzers advertising
	// CapabilityPackageUpdates may return updates instead of a full registry
	// only when this is true.
	AcceptPackageUpdates bool      `json:"acceptPackageUpdates,omitempty"`
	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"`
	PackageUpdates []*Package                   `json:"packageUpdates,omitempty"`
	AnalyzerRuns   []string                     `json:"analyzerRuns,omitempty"`
	AnalyzerStats  map[string]ReachabilityStats `json:"analyzerStats,omitempty"`
}

AnalyzeResult contains the registry after analyzer enrichment. An analyzer returns either Registry (the full annotated registry — the protocol v1 baseline) or, when the request set AcceptPackageUpdates, PackageUpdates: only the packages it touched. The host merges updates into its registry by PURL. When Registry is non-nil it wins and PackageUpdates is ignored.

type Analyzer 

type Analyzer interface {
	Descriptor() AnalyzerDescriptor
	// Ready reports whether the analyzer can run for the given request. It
	// returns nil when ready and a non-nil error describing the reason
	// otherwise. Implementations may perform lightweight, cancellable I/O and
	// should honor ctx.
	Ready(context.Context, AnalyzeRequest) error
	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"`
	// Capabilities advertises optional protocol features this analyzer
	// supports, such as CapabilityPackageUpdates.
	Capabilities []string `json:"capabilities,omitempty"`
	// ConfigSchema optionally documents the analyzer's configuration block as
	// a JSON Schema. Build it with ConfigSchemaFor.
	ConfigSchema json.RawMessage `json:"configSchema,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 AnalyzerModule added in v0.2.0 

type AnalyzerModule struct {
	Descriptor AnalyzerDescriptor
	New        func(context.Context, HostContext) (Analyzer, error)
}

AnalyzerModule declares one analyzer component.

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"`
	// DependencyDetailChanges contains canonical head-side transitions for a
	// diff audit. Scan and explain requests leave it empty.
	DependencyDetailChanges []DependencyDetailTransition `json:"dependencyDetailChanges,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.

It aliases AuditResult so plugin code can name payload types by role while sharing the same transport shape Bomly core uses internally.

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 reports whether the auditor can run for the given request. It
	// returns nil when ready and a non-nil error describing the reason
	// otherwise. Implementations may perform lightweight, cancellable I/O and
	// should honor ctx.
	Ready(context.Context, AuditRequest) error
	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"`
	// ConfigSchema optionally documents the auditor's configuration block as
	// a JSON Schema. Build it with ConfigSchemaFor.
	ConfigSchema json.RawMessage `json:"configSchema,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 AuditorModule added in v0.2.0 

type AuditorModule struct {
	Descriptor AuditorDescriptor
	New        func(context.Context, HostContext) (Auditor, error)
}

AuditorModule declares one auditor component.

type BaseAnalyzer 

type BaseAnalyzer struct{}

BaseAnalyzer provides default implementations of Analyzer's optional lifecycle methods: always ready and always applicable.

func (BaseAnalyzer) Applicable 

func (BaseAnalyzer) Applicable(context.Context, AnalyzeRequest) (bool, error)

Applicable reports the analyzer as applicable.

func (BaseAnalyzer) Ready 

func (BaseAnalyzer) Ready(context.Context, AnalyzeRequest) error

Ready reports the analyzer as ready.

type BaseAuditor 

type BaseAuditor struct{}

BaseAuditor provides default implementations of Auditor's optional lifecycle methods: always ready and always applicable.

func (BaseAuditor) Applicable 

func (BaseAuditor) Applicable(context.Context, AuditRequest) (bool, error)

Applicable reports the auditor as applicable.

func (BaseAuditor) Ready 

func (BaseAuditor) Ready(context.Context, AuditRequest) error

Ready reports the auditor as ready.

type BaseDetector 

type BaseDetector struct{}

BaseDetector provides default implementations of Detector's optional lifecycle methods: always ready and always applicable.

func (BaseDetector) Applicable 

func (BaseDetector) Applicable(context.Context, DetectionRequest) (bool, error)

Applicable reports the detector as applicable.

func (BaseDetector) Ready 

func (BaseDetector) Ready(context.Context, DetectionRequest) error

Ready reports the detector as ready.

type BaseMatcher 

type BaseMatcher struct{}

BaseMatcher provides default implementations of Matcher's optional lifecycle methods: always ready and always applicable.

func (BaseMatcher) Applicable 

func (BaseMatcher) Applicable(context.Context, MatchRequest) (bool, error)

Applicable reports the matcher as applicable.

func (BaseMatcher) Ready 

func (BaseMatcher) Ready(context.Context, MatchRequest) error

Ready reports the matcher as ready.

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)
	DetectorRemediationHints(context.Context, *RemediationHintRequest) (*RemediationHintResponse, 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)
	AnalyzerDescriptor(context.Context) (*AnalyzerDescriptor, error)
	AnalyzerReady(context.Context, *AnalyzeRequest) (*ReadyResponse, error)
	AnalyzerApplicable(context.Context, *AnalyzeRequest) (*ApplicableResponse, error)
	Analyze(context.Context, *AnalyzeRequest) (*AnalyzeResponse, 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 

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

	// FirstParty marks a node as the scanned project's own artifact (its root
	// package, a workspace member, a reactor module) rather than a consumed
	// third-party package. Only detectors set it, when synthesizing or matching
	// nodes they know belong to the build itself; imported documents (SBOM
	// scans) never do, because a component's declared type is an artifact kind,
	// not proof of ownership. Enrichment skips first-party nodes.
	FirstParty bool `json:"first_party,omitempty"`
}

Coordinates is the shared identity view embedded by Dependency and Package. It intentionally excludes graph-only fields (scopes, locations, package refs) and enrichment-only fields (licenses, vulnerabilities, scorecard) so detection-time graph nodes and matching-stage package records remain distinct domain models.

func (Coordinates) CanonicalPURL 

func (i Coordinates) CanonicalPURL() string

CanonicalPURL returns the canonical package URL for the identity.

func (Coordinates) DisplayName 

func (i Coordinates) DisplayName() string

DisplayName returns the package name in its ecosystem-native form: "@org/name" for npm-family packages, "org/name" for path-style ecosystems (Go, Composer), and "org:name" otherwise. Unlike QualifiedName it is a presentation label only and must never be used as an identity key.

func (Coordinates) EcosystemName 

func (i Coordinates) EcosystemName() string

EcosystemName returns the package name in the form its ecosystem uses as an identity: "@org/name" for npm, "org:name" for Maven-family coordinates, and "org/name" for the path-style namespaced ecosystems (Go, Composer, Swift, GitHub Actions). This is the name external advisory databases, SBOM documents, and scanners such as Grype and Syft key on, so anything building a lookup for a package must derive it from here rather than from the bare Name — Name alone drops the npm scope and matches the unscoped package's advisories.

Joining is opt-in per ecosystem, and everything else keeps the bare Name, because Org is not always part of the package name. For OS packages Org is the distro that shipped the package (`Org: "alpine"` from `pkg:apk/alpine/libcrypto3`), and Grype's distro-namespace matchers query `libcrypto3`; joining would miss every OS advisory. The same holds for any other ecosystem whose PURL namespace names a vendor or channel rather than part of the package's own identity.

func (Coordinates) IdentityKey 

func (i Coordinates) IdentityKey() string

IdentityKey returns a stable package identity without version information.

func (Coordinates) QualifiedName 

func (i Coordinates) QualifiedName() string

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

func (Coordinates) StableID 

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"`
	Relationship DependencyRelationship `json:"relationship,omitempty"`
	Source       DependencySource       `json:"source,omitempty"`
	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, using the ecosystem-native name form (e.g. "@org/name" for npm).

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) RegistryMatchEligible 

func (d *Dependency) RegistryMatchEligible() bool

RegistryMatchEligible reports whether this dependency occurrence may be sent to external package matchers. First-party and manifest nodes are never eligible. Project, workspace, file, Git, and arbitrary URL occurrences are normally excluded. Swift source-control packages remain eligible because their repository URL is the canonical SwiftURL package identity used by vulnerability sources. An application type imported from an SBOM is an artifact kind rather than proof of ownership and remains eligible unless it is marked first-party. An omitted source stays eligible for protocol-v1 and legacy detector compatibility.

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 DependencyDetailField 

type DependencyDetailField string

DependencyDetailField identifies one occurrence property that changed independently of package identity or version. 

const (
	// DependencyDetailRelationship is a direct, transitive, or unknown
	// relationship change.
	DependencyDetailRelationship DependencyDetailField = "relationship"
	// DependencyDetailSource is a registry, workspace, file, Git, URL, or
	// project source change.
	DependencyDetailSource DependencyDetailField = "source"
	// DependencyDetailRegistryEligibility indicates that external registry
	// matching eligibility changed.
	DependencyDetailRegistryEligibility DependencyDetailField = "registry_eligibility"
)

type DependencyDetailReviewReason 

type DependencyDetailReviewReason string

DependencyDetailReviewReason explains why a dependency detail change should receive extra review. 

const (
	// DependencyDetailReviewSourceGit indicates that the dependency now comes
	// from a Git repository.
	DependencyDetailReviewSourceGit DependencyDetailReviewReason = "source-changed-to-git"
	// DependencyDetailReviewSourceURL indicates that the dependency now comes
	// from an arbitrary URL.
	DependencyDetailReviewSourceURL DependencyDetailReviewReason = "source-changed-to-url"
)

type DependencyDetailTransition 

type DependencyDetailTransition struct {
	Before                 *Dependency             `json:"before"`
	After                  *Dependency             `json:"after"`
	ChangedFields          []DependencyDetailField `json:"changedFields"`
	BeforeRelationship     DependencyRelationship  `json:"beforeRelationship,omitempty"`
	AfterRelationship      DependencyRelationship  `json:"afterRelationship,omitempty"`
	BeforeRegistryEligible bool                    `json:"beforeRegistryEligible"`
	AfterRegistryEligible  bool                    `json:"afterRegistryEligible"`
}

DependencyDetailTransition captures same-identity occurrence detail changes. Version changes remain represented separately by VersionChange.

func CloneDependencyDetailTransitions 

func CloneDependencyDetailTransitions(transitions []DependencyDetailTransition) []DependencyDetailTransition

CloneDependencyDetailTransitions returns a deep copy of dependency detail transitions suitable for crossing component and plugin boundaries.

func CompareDependencyDetails 

func CompareDependencyDetails(baseGraph, headGraph *Graph, before, after *Dependency) (DependencyDetailTransition, bool)

CompareDependencyDetails returns a transition when relationship, source, or registry-matching eligibility differs between two occurrences. It is exported so trusted fuzzy identity reconciliation can use the same canonical classifier as Compare.

func (DependencyDetailTransition) NeedsReview 

func (t DependencyDetailTransition) NeedsReview() bool

NeedsReview reports whether this detail change has at least one review reason.

func (DependencyDetailTransition) ReviewReasons 

func (t DependencyDetailTransition) ReviewReasons() []DependencyDetailReviewReason

ReviewReasons returns the reasons this detail change needs extra review. The result is deterministic and does not treat missing evidence, coverage gains, or relationship-only changes as review signals.

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 DependencyRelationship 

type DependencyRelationship string

DependencyRelationship describes how a dependency occurrence relates to the application or manifest root that owns its graph. 

const (
	// DependencyRelationshipDirect identifies a dependency declared by a root.
	DependencyRelationshipDirect DependencyRelationship = "direct"
	// DependencyRelationshipTransitive identifies a dependency reached through another dependency.
	DependencyRelationshipTransitive DependencyRelationship = "transitive"
	// DependencyRelationshipUnknown identifies a dependency whose parent could not be recovered.
	DependencyRelationshipUnknown DependencyRelationship = "unknown"
)

func MergeDependencyRelationship 

func MergeDependencyRelationship(current, next DependencyRelationship) DependencyRelationship

MergeDependencyRelationship combines occurrence relationships for a merged graph, retaining the strongest known project relationship.

func ParseDependencyRelationship 

func ParseDependencyRelationship(value string) DependencyRelationship

ParseDependencyRelationship normalizes a dependency relationship value.

func RelationshipForPath 

func RelationshipForPath(path []*Dependency) DependencyRelationship

RelationshipForPath returns the explicit target relationship when present, otherwise derives directness from a root-to-target path.

type DependencySource 

type DependencySource string

DependencySource describes how a dependency occurrence is resolved. 

const (
	DependencySourceRegistry  DependencySource = "registry"
	DependencySourceProject   DependencySource = "project"
	DependencySourceWorkspace DependencySource = "workspace"
	DependencySourceFile      DependencySource = "file"
	DependencySourceGit       DependencySource = "git"
	DependencySourceURL       DependencySource = "url"
)

type DetectRequest 

type DetectRequest = DetectionRequest

DetectRequest is the detector request payload exposed to plugins.

It aliases DetectionRequest so plugin code can name payload types by role while sharing the same transport shape Bomly core uses internally.

type DetectResponse 

type DetectResponse = DetectionResult

DetectResponse is the detector response payload exposed to plugins.

It aliases DetectionResult so plugin code can name payload types by role while sharing the same transport shape Bomly core uses internally.

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 tells a detector that the user enabled debug output
	// and accepts the detector's raw subprocess diagnostics in that output.
	AllowStdErrLogging bool `json:"allowStdErrLogging,omitempty"`
	// Stderr and Verbose are process-local fields used by built-in detectors.
	// Stderr is nil unless debug output is enabled. Verbose mirrors
	// AllowStdErrLogging for compatibility with existing detector code.
	Stderr  io.Writer `json:"-"`
	Verbose bool      `json:"-"`
	// Logger is a request-scoped logger injected by the pipeline, already
	// bound to the subproject and detector this request targets. It lets a
	// detector instance that is shared across concurrently-resolved
	// subprojects emit log lines that identify which subproject they belong
	// to. It is process-local and never serialized. Use DetectorLogger to
	// read it with a safe fallback.
	Logger *zap.Logger `json:"-"`
}

DetectionRequest defines input for dependency graph resolution.

func (DetectionRequest) DetectorLogger 

func (r DetectionRequest) DetectorLogger(fallback *zap.Logger) *zap.Logger

DetectorLogger returns the most specific non-nil logger for this request: the request-scoped Logger injected by the pipeline (carrying subproject and detector context) when present, otherwise the supplied fallback (typically the detector's own instance logger), otherwise a no-op logger. It never returns nil, so callers can drop the usual "if logger == nil" guard.

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"`
	// FallbackFrom names the planned primary detector that failed before a
	// fallback detector produced this result. Empty for routine applicability
	// hand-off between chained detectors.
	FallbackFrom string `json:"fallbackFrom,omitempty"`
	// FallbackReason is the human-readable cause of the primary detector's
	// failure, e.g. "not ready: java executable not found on PATH".
	FallbackReason string          `json:"fallbackReason,omitempty"`
	Graphs         *GraphContainer `json:"graphs,omitempty"`
	// Warnings are non-fatal problems the detector found while resolving: the
	// graphs above are usable, but something about the project will break or
	// degrade an install elsewhere. The engine fills in each warning's
	// Subproject and surfaces them alongside the ones it observes itself.
	Warnings []DetectorWarning `json:"warnings,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 reports whether the detector can run for the given request. It
	// returns nil when ready and a non-nil error describing the reason
	// (e.g. a missing toolchain) otherwise. Implementations may perform
	// lightweight, cancellable I/O (such as probing for a runtime) and should
	// honor ctx.
	Ready(context.Context, DetectionRequest) error
	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"`
	// RemediationCapabilities advertises optional, read-only support for
	// package-manager-specific remediation strategies. Core calls the optional
	// provider only when this list is non-empty.
	RemediationCapabilities []RemediationCapability `json:"remediationCapabilities,omitempty"`
	// IgnoredDirectories lists directory basename globs (Go
	// path.Match syntax) that recursive subproject discovery must not descend
	// into because they hold third-party installs, vendored dependencies, or
	// build outputs for this detector's ecosystem (e.g. "node_modules",
	// "target"). Discovery aggregates these across every registered detector,
	// including external plugins. Optional; omitted by older plugins.
	IgnoredDirectories []string `json:"ignoredDirectories,omitempty"`
	// IgnoredDirectoryMarkers lists file names whose presence inside
	// a directory marks that directory as ignored during recursive discovery
	// regardless of its name (e.g. "pyvenv.cfg" identifies a Python
	// virtualenv). Optional; omitted by older plugins.
	IgnoredDirectoryMarkers []string `json:"ignoredDirectoryMarkers,omitempty"`
	// ConfigSchema optionally documents the detector's configuration block as
	// a JSON Schema. Build it with ConfigSchemaFor.
	ConfigSchema json.RawMessage `json:"configSchema,omitempty"`
}

DetectorDescriptor describes a detector registration.

func (DetectorDescriptor) Clone 

func (d DetectorDescriptor) Clone() DetectorDescriptor

Clone returns a deep copy of the detector descriptor.

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. Implement this only for detectors that need to prepare project dependencies before reading them; Bomly calls it only when install-first execution is requested.

type DetectorModule added in v0.2.0 

type DetectorModule struct {
	Descriptor DetectorDescriptor
	Support    []PackageManagerSupport
	// TargetKinds lists the execution target kinds the detector supports.
	// Empty means the host derives the default [filesystem, git-repository],
	// mirroring the managed-plugin derivation.
	TargetKinds []ExecutionTargetKind
	New         func(context.Context, HostContext) (Detector, error)
}

DetectorModule declares one detector component: its static descriptor, package-manager support, and a constructor invoked once per execution.

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 DetectorRemediationProvider 

type DetectorRemediationProvider interface {
	RemediationHints(context.Context, RemediationHintRequest) (RemediationHintResponse, error)
}

DetectorRemediationProvider optionally contributes read-only package-manager evidence after vulnerability enrichment.

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 DetectorWarning 

type DetectorWarning struct {
	Type       DetectorWarningType `json:"type"`
	Code       DetectorWarningCode `json:"code,omitempty"`
	Source     string              `json:"source,omitempty"`
	Subproject string              `json:"subproject,omitempty"`
	Manifest   string              `json:"manifest,omitempty"`
	Message    string              `json:"message"`
}

DetectorWarning is one non-fatal problem found while detecting dependencies. Detectors return warnings alongside the graphs they resolve; the engine adds the ones it observes around them (a failed chain, a fallback). Every warning travels the same way to every surface, so a consumer never has to know which of the two produced it.

Source names the detector or tool the warning is about ("maven-detector", "pnpm"). Subproject and Manifest locate it when known; the engine fills in Subproject, so detectors only set Manifest.

func (DetectorWarning) DegradesCoverage 

func (w DetectorWarning) DegradesCoverage() bool

DegradesCoverage reports whether this warning means the graph may be incomplete. It is shorthand for Type.DegradesCoverage.

type DetectorWarningCode 

type DetectorWarningCode string

DetectorWarningCode identifies the specific check that produced a warning. It is empty for warnings the engine synthesizes from a detector failure, where Type already carries the full meaning. 

const (
	// DetectorWarningCodeLockfileFormat means the committed lockfile's format
	// version disagrees with the package-manager version the project declares.
	DetectorWarningCodeLockfileFormat DetectorWarningCode = "lockfile-format-mismatch"
	// DetectorWarningCodeLockfileUnsupported means the project commits a
	// lockfile the declared package manager does not read.
	DetectorWarningCodeLockfileUnsupported DetectorWarningCode = "lockfile-unsupported"
	// DetectorWarningCodeEnginesConstraint means a declared engines constraint
	// contradicts another declaration in the same project.
	DetectorWarningCodeEnginesConstraint DetectorWarningCode = "engines-constraint-mismatch"
	// DetectorWarningCodeInstallGate means an install policy rejects versions by
	// age or publish date, so a freshly published fix version cannot install.
	DetectorWarningCodeInstallGate DetectorWarningCode = "install-policy-gate"
)

type DetectorWarningType 

type DetectorWarningType string

DetectorWarningType classifies a detector warning by what it means for the run. It is the field policy decisions branch on: see DegradesCoverage. 

const (
	// DetectorWarningResolutionFailure means a detector chain failed for a
	// subproject and the scan continued without that subproject's dependencies.
	DetectorWarningResolutionFailure DetectorWarningType = "resolution-failure"
	// DetectorWarningFallback means a fallback detector produced the graph after
	// the planned primary detector failed, so transitive dependencies may be
	// missing.
	DetectorWarningFallback DetectorWarningType = "fallback"
	// DetectorWarningPackageManager means the graph is sound, but the project's
	// package-manager configuration will break or degrade an install elsewhere —
	// typically in CI.
	DetectorWarningPackageManager DetectorWarningType = "package-manager"
)

func (DetectorWarningType) DegradesCoverage 

func (t DetectorWarningType) DegradesCoverage() bool

DegradesCoverage reports whether the warning means the dependency graph may be incomplete, and therefore that findings may be missing. Consumers that require complete coverage before recording a decision — writing a finding baseline, for example — gate on this rather than on the presence of any warning: a package-manager mismatch says nothing about coverage.

type Diff 

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

Diff summarizes the dependency changes between two graphs.

func Compare 

func Compare(base, head *Graph) Diff

Compare returns added, removed, version-changed, and detail-changed 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 

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 

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 ExecutionMode added in v0.2.0 

type ExecutionMode string

ExecutionMode identifies how a component instance is being executed. 

const (
	// ExecutionEmbedded marks a component compiled into the host binary and
	// registered in-process.
	ExecutionEmbedded ExecutionMode = "embedded"
	// ExecutionManaged marks a component running in its own plugin process
	// managed by the host over the plugin transport.
	ExecutionManaged ExecutionMode = "managed"
)

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. Vulnerability constraints form an AND-set. Other finding types may define independent gates, such as a dependency source change in a diff.

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. "source-change" yields a SourceChangeConstraint. 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"
	// SourceChangeConstraint matches package-auditor findings for dependency
	// source changes in a diff.
	SourceChangeConstraint FailOnKind = "source-change"
)

type FallbackDetector deprecated 

type FallbackDetector interface {
	FallbackDetector() Detector
}

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

Deprecated: the host executes planned detector chains; fallback interfaces are no longer consulted. The interface is kept for one release so existing implementations keep compiling.

type Finding 

type Finding struct {
	ID           string              `json:"id"`
	Kind         FindingKind         `json:"kind"`
	Title        string              `json:"title,omitempty"`
	Severity     SeverityLevel       `json:"severity,omitempty"`
	PolicyStatus FindingPolicyStatus `json:"policy_status,omitempty"`
	Reasons      []string            `json:"reasons,omitempty"`
	Source       string              `json:"source,omitempty"`
	Auditor      string              `json:"auditor,omitempty"`
	// RuleID is the stable auditor rule that produced the finding. Unlike ID,
	// it must not contain package versions or project-specific occurrence data.
	RuleID           string    `json:"rule_id,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.

func (*Finding) UnmarshalJSON 

func (f *Finding) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts the current policy_status field and the protocol-v1 legacy field so existing external auditor plugins continue to interoperate.

type FindingKind 

type FindingKind string

FindingKind categorizes audit findings by the underlying concern the auditor is reporting on. Built-in auditors normally emit these kinds: 

FindingKindVulnerability — advisory findings from the vulnerability auditor
FindingKindLicense       — emitted by the license auditor
FindingKindPackage       — package policy findings, including dependency
                          source changes

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

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

type FindingPolicyDecision 

type FindingPolicyDecision struct {
	Status FindingPolicyStatus
	Source string
	Reason string
}

FindingPolicyDecision is a resolver's proposed policy status for one finding. Source and Reason provide diagnostic provenance.

type FindingPolicyResolver 

type FindingPolicyResolver interface {
	ResolveFindingPolicy(context.Context, Finding, *PackageRegistry) (FindingPolicyDecision, bool)
}

FindingPolicyResolver may refine a finding's policy status during auditing. Resolvers must not remove findings or rewrite their evidence.

type FindingPolicyStatus 

type FindingPolicyStatus string

FindingPolicyStatus controls whether a finding fails evaluation, remains a warning, or is accepted by project policy. 

const (
	FindingPolicyStatusFail FindingPolicyStatus = "fail"
	FindingPolicyStatusWarn FindingPolicyStatus = "warn"
	// FindingPolicyStatusSuppressed keeps a finding visible while excluding it
	// from policy-failure evaluation.
	FindingPolicyStatusSuppressed FindingPolicyStatus = "suppressed"
)

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 

type FixAvailableKind string

FixAvailableKind identifies why a fix version was selected. 

const (
	FixAvailableFirstObserved FixAvailableKind = "first-observed"
)

type FixState 

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. External plugins normally obtain this from HTTPClientConfigFromEnv instead of building it by hand, so Bomly-managed proxy and CA settings are honored.

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 or plugin process. Reuse one provider for repeated outbound calls so connection pools, proxy settings, and TLS configuration stay consistent.

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. Use this in external plugins that make outbound HTTP calls.

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 HostContext added in v0.2.0 

type HostContext interface {
	Logger() *zap.Logger
	HTTPClient() *HTTPClientProvider
	Runtime() RuntimeInfo
	// DecodeConfig unmarshals the component's own configuration block into v.
	// Embedded execution sources it from the host config's kind-scoped
	// plugins.<kind>.<name> block; managed execution sources it from the
	// config file the host passes via BOMLY_PLUGIN_CONFIG_FILE. Identical
	// JSON semantics both ways.
	DecodeConfig(v any) error
}

HostContext is the only channel through which a component reaches host services. The same contract is satisfied by the embedded host (in-process registration) and the managed host (plugin subprocess), so a component written against it runs unchanged in both execution modes.

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 

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"
	// ManifestKindBunLock identifies Bun text lockfiles.
	ManifestKindBunLock ManifestKind = "bun.lock"
	// 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"`
	Resolution *ResolutionMetadata `json:"resolution,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"`
	// AcceptPackageUpdates signals that the host understands
	// MatchResult.PackageUpdates. Matchers advertising
	// CapabilityPackageUpdates may return updates instead of a full registry
	// only when this is true.
	AcceptPackageUpdates bool      `json:"acceptPackageUpdates,omitempty"`
	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.

It aliases MatchResult so plugin code can name payload types by role while sharing the same transport shape Bomly core uses internally.

type MatchResult 

type MatchResult struct {
	Registry       *PackageRegistry `json:"registry,omitempty"`
	PackageUpdates []*Package       `json:"packageUpdates,omitempty"`
	MatcherStats   MatcherStats     `json:"matcherStats,omitempty"`
}

MatchResult contains the package registry after matcher enrichment.

A matcher returns either Registry (the full enriched registry — the protocol v1 baseline) or, when the request set AcceptPackageUpdates, PackageUpdates: only the packages it touched. The host merges updates into its registry by PURL. When Registry is non-nil it wins and PackageUpdates is ignored.

type Matcher 

type Matcher interface {
	Descriptor() MatcherDescriptor
	// Ready reports whether the matcher can run for the given request. It
	// returns nil when ready and a non-nil error describing the reason
	// otherwise. Implementations may perform lightweight, cancellable I/O and
	// should honor ctx.
	Ready(context.Context, MatchRequest) error
	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"`
	// Capabilities advertises optional protocol features this matcher
	// supports, such as CapabilityPackageUpdates.
	Capabilities []string `json:"capabilities,omitempty"`
	// ConfigSchema optionally documents the matcher's configuration block as
	// a JSON Schema. Build it with ConfigSchemaFor.
	ConfigSchema json.RawMessage `json:"configSchema,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 MatcherModule added in v0.2.0 

type MatcherModule struct {
	Descriptor MatcherDescriptor
	New        func(context.Context, HostContext) (Matcher, error)
}

MatcherModule declares one matcher component.

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 Module added in v0.2.0 

type Module struct {
	Kind     PluginKind
	Detector *DetectorModule
	Matcher  *MatcherModule
	Auditor  *AuditorModule
	Analyzer *AnalyzerModule
}

Module is the execution-neutral packaging of one component. Exactly one of the role fields must be set, and it must match Kind. The same Module value can be registered embedded by the host or served managed via ServeModule.

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"`
	Remediation     *PackageRemediation `json:"remediation,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, using the ecosystem-native name form (e.g. "@org/name" for npm).

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. The type is string-backed so plugins can pass custom values while Bomly grows first-class constants; use PackageManagerOther when no specific manager value is appropriate. 

const (
	PackageManagerUnknown       PackageManager = ""
	PackageManagerNPM           PackageManager = "npm"
	PackageManagerPNPM          PackageManager = "pnpm"
	PackageManagerYarn          PackageManager = "yarn"
	PackageManagerBun           PackageManager = "bun"
	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"`
	// MultiModule marks that the detector natively expands nested
	// workspace/reactor modules for this package manager from a root manifest
	// (Maven reactors, npm/pnpm/yarn workspaces, cargo workspace members,
	// ...). Recursive discovery prunes nested subprojects for the same
	// package manager below a directory where a native multi-module manager
	// was detected, so the same modules are not scanned twice. Optional;
	// omitted by older plugins.
	MultiModule bool `json:"multiModule,omitempty"`
}

PackageManagerSupport records package-manager discovery metadata for a detector. External detector plugins return this so Bomly can include them in subproject discovery and scan planning before the detector runs.

func Support 

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

Support returns package-manager discovery metadata for a detector.

func (PackageManagerSupport) WithMultiModule 

func (s PackageManagerSupport) WithMultiModule() PackageManagerSupport

WithMultiModule returns a copy of the support entry marked as natively expanding nested workspace/reactor modules from a root manifest, opting the package manager into recursive-discovery ancestor pruning.

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 ApplyPackageUpdates 

func ApplyPackageUpdates(registry *PackageRegistry, updates []*Package) *PackageRegistry

ApplyPackageUpdates merges package-update deltas returned by a matcher or analyzer (MatchResult.PackageUpdates / AnalyzeResult.PackageUpdates) into the registry. Each update is merged into any existing record with the same PURL via the registry's standard merge semantics; updates without a PURL are ignored. It returns the registry for convenience.

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 PackageRemediation 

type PackageRemediation struct {
	Status             PackageRemediationStatus       `json:"status"`
	RecommendedVersion string                         `json:"recommended_version,omitempty"`
	Suggestions        []PackageRemediationSuggestion `json:"suggestions,omitempty"`
}

PackageRemediation summarizes the fix evidence already present on a package's enriched vulnerabilities.

func (*PackageRemediation) Clone 

func (r *PackageRemediation) Clone() *PackageRemediation

Clone returns a copy of the package remediation summary.

type PackageRemediationStatus 

type PackageRemediationStatus string

PackageRemediationStatus describes how completely vulnerability enrichment identifies a safe package version. 

const (
	// PackageRemediationComplete means every vulnerability has usable fix
	// evidence and one recommended package version can address all of them.
	PackageRemediationComplete PackageRemediationStatus = "complete"
	// PackageRemediationPartial means fix evidence exists, but it cannot produce
	// one complete package recommendation.
	PackageRemediationPartial PackageRemediationStatus = "partial"
	// PackageRemediationUnavailable means every vulnerability explicitly reports
	// that no fix is available.
	PackageRemediationUnavailable PackageRemediationStatus = "unavailable"
	// PackageRemediationUnknown means fix evidence is missing or contradictory.
	PackageRemediationUnknown PackageRemediationStatus = "unknown"
)

type PackageRemediationSuggestion 

type PackageRemediationSuggestion struct {
	AffectedDependencyRefs       []string          `json:"affected_dependency_refs"`
	SuggestedActionDependencyRef string            `json:"suggested_action_dependency_ref,omitempty"`
	ManifestPath                 string            `json:"manifest_path,omitempty"`
	Action                       RemediationAction `json:"action"`
	OverrideAdvice               string            `json:"override_advice,omitempty"`
}

PackageRemediationSuggestion describes one occurrence-scoped action for the containing package. AffectedDependencyRefs identify occurrences of the vulnerable package. SuggestedActionDependencyRef identifies the direct dependency or manifest anchor the suggested action targets.

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 

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 

func ParsePackageType(value string) PackageType

ParsePackageType normalizes a package role string.

func (PackageType) String 

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"`
	// Reason explains why the plugin is not ready. It is ignored when Ready is
	// true and surfaced to users (and resolution errors) when Ready is false.
	Reason string `json:"reason,omitempty"`
}

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 

type ReferenceType string

ReferenceType identifies the role of a vulnerability reference URL. 

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

type RemediationAction 

type RemediationAction string

RemediationAction identifies the user action suggested for one or more occurrences of an enriched vulnerable package. 

const (
	// RemediationActionDirectBump suggests updating a directly declared package.
	RemediationActionDirectBump RemediationAction = "direct-bump"
	// RemediationActionTransitiveOverride suggests using a package-manager
	// override for a transitive package.
	RemediationActionTransitiveOverride RemediationAction = "transitive-override"
	// RemediationActionLockfileRefresh suggests asking the package manager to
	// resolve a newer transitive package version.
	RemediationActionLockfileRefresh RemediationAction = "lockfile-refresh"
	// RemediationActionNoFixUpstream reports that every vulnerability explicitly
	// lacks an upstream fix.
	RemediationActionNoFixUpstream RemediationAction = "no-fix-upstream"
	// RemediationActionManualReview reports that available evidence cannot
	// support a safe, concrete automated suggestion.
	RemediationActionManualReview RemediationAction = "manual-review"
)

type RemediationCapability 

type RemediationCapability struct {
	SupportedManagers []PackageManager    `json:"supportedManagers,omitempty"`
	Actions           []RemediationAction `json:"actions,omitempty"`
}

RemediationCapability advertises the occurrence-scoped strategies for which a detector can provide package-manager-specific evidence. Capabilities do not grant authority to choose final remediation or modify a project.

type RemediationHint 

type RemediationHint struct {
	DependencyRef string                    `json:"dependencyRef"`
	ManifestPath  string                    `json:"manifestPath,omitempty"`
	Strategies    []RemediationStrategyHint `json:"strategies,omitempty"`
}

RemediationHint contributes package-manager evidence for one detected dependency occurrence.

type RemediationHintRequest 

type RemediationHintRequest struct {
	ProjectPath string           `json:"projectPath,omitempty"`
	Detection   DetectionResult  `json:"detection"`
	Registry    *PackageRegistry `json:"registry,omitempty"`
}

RemediationHintRequest supplies completed detection and enrichment evidence to an optional detector remediation provider.

type RemediationHintResponse 

type RemediationHintResponse struct {
	Hints       []RemediationHint `json:"hints,omitempty"`
	Diagnostics []string          `json:"diagnostics,omitempty"`
}

RemediationHintResponse contains optional read-only detector evidence.

type RemediationStrategyHint 

type RemediationStrategyHint struct {
	Action RemediationAction `json:"action"`
	Advice string            `json:"advice,omitempty"`
}

RemediationStrategyHint is read-only detector evidence that a strategy is available for one occurrence. Advice is detector-owned, action-specific package-manager guidance. For example, a transitive-override hint can explain the manager's override syntax, while a lockfile-refresh hint can provide the normal refresh command. Core validates and bounds this text, then retains authority over the final action.

type ResolutionFallback 

type ResolutionFallback struct {
	From   string `json:"from"`
	Reason string `json:"reason,omitempty"`
}

ResolutionFallback identifies the primary detector that failed before a fallback detector produced the graph, and why it failed.

type ResolutionMetadata 

type ResolutionMetadata struct {
	Method            ResolutionMethod `json:"method,omitempty"`
	InstallExecuted   bool             `json:"install_executed"`
	InstallCommand    []string         `json:"install_command,omitempty"`
	InstallWorkingDir string           `json:"install_working_dir,omitempty"`
	// Fallback records that a fallback detector produced this graph after the
	// planned primary detector failed (not routine applicability hand-off).
	Fallback *ResolutionFallback `json:"fallback,omitempty"`
}

ResolutionMetadata describes how a detector resolved a manifest graph.

type ResolutionMethod 

type ResolutionMethod string

ResolutionMethod identifies how a detector produced a manifest graph. 

const (
	// ResolutionMethodLockfile means the graph came from a deterministic lockfile parser.
	ResolutionMethodLockfile ResolutionMethod = "lockfile"
	// ResolutionMethodIsolatedInstall means Bomly installed dependencies into its own isolated environment.
	ResolutionMethodIsolatedInstall ResolutionMethod = "isolated-install"
	// ResolutionMethodProjectEnvironment means Bomly inspected an existing project-managed environment.
	ResolutionMethodProjectEnvironment ResolutionMethod = "project-environment"
	// ResolutionMethodManifestOnly means Bomly parsed a manifest without transitive install metadata.
	ResolutionMethodManifestOnly ResolutionMethod = "manifest-only"
)

type RiskBand 

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 RuntimeInfo added in v0.2.0 

type RuntimeInfo struct {
	// CoreVersion is the host core version when known; empty otherwise.
	CoreVersion string
	// Execution reports whether the component runs embedded or managed.
	Execution ExecutionMode
}

RuntimeInfo describes the host runtime a component executes under.

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 ServedAnalyzer 

type ServedAnalyzer interface {
	Descriptor(context.Context) (*AnalyzerDescriptor, error)
	Ready(context.Context, *AnalyzeRequest) (*ReadyResponse, error)
	Applicable(context.Context, *AnalyzeRequest) (*ApplicableResponse, error)
	Analyze(context.Context, *AnalyzeRequest) (*AnalyzeResponse, error)
}

ServedAnalyzer is the analyzer interface implemented by external analyzer plugins. Analyzers read the dependency graph and PURL-keyed package registry and annotate Vulnerability.Reachability on registry packages.

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 implemented by external auditor plugins. Auditors read graph and registry data and return reference-style findings, risk scores, and run metadata.

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 implemented by external detector plugins. A detector describes its identity and package-manager support, reports readiness/applicability for a planned scan target, and returns one or more manifest-scoped dependency graphs from Detect.

type ServedDetectorRemediationProvider 

type ServedDetectorRemediationProvider interface {
	RemediationHints(context.Context, *RemediationHintRequest) (*RemediationHintResponse, error)
}

ServedDetectorRemediationProvider optionally supplies read-only, package-manager-specific remediation evidence.

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 implemented by external matcher plugins. Matchers read the dependency graph and PURL-keyed package registry, then return the registry with package enrichment such as licenses, vulnerabilities, lifecycle data, or other metadata.

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 

type SeverityLevel string

SeverityLevel is Bomly's normalized severity band.

It carries two parallel vocabularies over one ordered scale, mirroring how GitHub presents code-scanning results:

  • CVSS bands (critical/high/medium/low) are used for vulnerabilities, which also drive SARIF `security-severity`; GitHub renders them as Critical/High/Medium/Low.
  • GitHub levels (error/warning/note) are used for findings that have no CVSS score (license, package); GitHub renders the SARIF `level` directly as Error/Warning/Note.

The two vocabularies share a single rank ladder (see SeverityRank): error ≡ high tier, warning ≡ medium tier, note ≡ low tier. 

const (
	// SeverityUnknown indicates that no severity could be determined.
	SeverityUnknown SeverityLevel = "unknown"
	// SeverityNA indicates that severity does not apply to the finding kind.
	//
	// Deprecated: kept for backward-compatible parsing only. New findings that
	// lack a CVSS score should use SeverityError/SeverityWarning/SeverityNote.
	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"

	// SeverityNote is the GitHub-aligned level for low-impact findings without a
	// CVSS score. Ranks alongside SeverityLow.
	SeverityNote SeverityLevel = "note"
	// SeverityWarning is the GitHub-aligned level for findings without a CVSS
	// score that warrant attention. Ranks alongside SeverityMedium.
	SeverityWarning SeverityLevel = "warning"
	// SeverityError is the GitHub-aligned level for high-impact findings without
	// a CVSS score. Ranks alongside SeverityHigh.
	SeverityError SeverityLevel = "error"
)

func ParseSeverityLevel 

func ParseSeverityLevel(value string) SeverityLevel

ParseSeverityLevel normalizes a severity string into a SeverityLevel.

type SeverityType 

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 

type SymbolKind string

SymbolKind identifies a vulnerable or reachable code symbol kind. 

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

type VEXStatus 

type VEXStatus string

VEXStatus identifies a finding's VEX status. 

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 

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 the vulnerability constraints in an AND-set. Source-change constraints apply only to package findings and are ignored here. When constraints is empty, every vulnerability matches (the historical behavior of `--audit` without `--fail-on`). A list containing only non-vulnerability constraints also leaves vulnerability matching unchanged.

Source Files

View all Source files

Directories

Path Synopsis
Package conformance provides a reusable test suite that plugin authors run against their sdk.Module to verify it satisfies the Bomly plugin contract before shipping: module and descriptor validity, JSON round-trip stability, construction through a HostContext, the Ready/Applicable lifecycle contract, role-specific capabilities such as the package-updates delta protocol, and (optionally) manifest identity and a real managed-transport probe of the built plugin binary.
 Package conformance provides a reusable test suite that plugin authors run against their sdk.Module to verify it satisfies the Bomly plugin contract before shipping: module and descriptor validity, JSON round-trip stability, construction through a HostContext, the Ready/Applicable lifecycle contract, role-specific capabilities such as the package-updates delta protocol, and (optionally) manifest identity and a real managed-transport probe of the built plugin binary.
Package detectorkit provides shared helper functions for detector implementations: manifest metadata inference, source-position wiring, remediation hint assembly, subgraph partitioning, and build-tool readiness and timeout helpers.
 Package detectorkit provides shared helper functions for detector implementations: manifest metadata inference, source-position wiring, remediation hint assembly, subgraph partitioning, and build-tool readiness and timeout helpers.
Package filecache provides shared on-disk caching helpers for matcher, analyzer, and detector implementations.
 Package filecache provides shared on-disk caching helpers for matcher, analyzer, and detector implementations.
Package logkit provides secret-safe subprocess logging helpers shared by Bomly components: argument and URL sanitizers, standard DEBUG command fields, and a counting stderr writer.
 Package logkit provides secret-safe subprocess logging helpers shared by Bomly components: argument and URL sanitizers, standard DEBUG command fields, and a counting stderr writer.
Package matcherkit contains shared helper functions for matcher implementations.
 Package matcherkit contains shared helper functions for matcher implementations.
Package system provides bounded filesystem reads and small OS helpers (exec, path, and environment wrappers) shared by Bomly components.
 Package system provides bounded filesystem reads and small OS helpers (exec, path, and environment wrappers) shared by Bomly components.
Package testkit provides test helpers for component modules and external plugins: fuzz-target invariants, Go binary builders for fake tools, and lockfile position assertions.
 Package testkit provides test helpers for component modules and external plugins: fuzz-target invariants, Go binary builders for fake tools, and lockfile position assertions.

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.