runtime

package
v0.14.0 Latest Latest
Warning

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

Go to latest
Published: Oct 3, 2026 License: Apache-2.0 Imports: 19 Imported by: 10

Documentation

Overview

Package plugin is the managed-plugin runtime: it serves one component as a Bomly plugin binary over the HashiCorp go-plugin gRPC transport, and hands the host the matching Client for the other end of that connection.

Managed plugins are native Go binaries that Bomly launches as separate subprocesses. 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 packages its component as a plugin.Module and serves it from main:

func main() {
	runtime.ServeModule(myModule)
}

ServeModule builds the managed plugin.HostContext (a stderr logger, an HTTP client provider from the BOMLY_HTTP_* environment via httpkit, and config decoding from the file named by BOMLY_PLUGIN_CONFIG_FILE) and adapts the component to the wire protocol. ServeDetector, ServeMatcher, ServeAuditor, and ServeAnalyzer serve a hand-written ServedDetector, ServedMatcher, ServedAuditor, or ServedAnalyzer directly; they use the same request and response types as the in-process contract in the plugin package.

The wire contract, bomly.plugin.v1, is JSON over gRPC and strictly additive: every payload type lives in the plugin and model packages, where the omitempty coverage tests guard it. Nothing in this package is a payload.

On the host side, HandshakeConfig and ClientPluginMap configure a go-plugin client, and the dispensed value implements Client.

Index

Constants

View Source
const (
	// 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 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.

Variables

This section is empty.

Functions

func ClientPluginMap

func ClientPluginMap() map[string]hplugin.Plugin

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

func DecodePluginConfigFromEnv

func DecodePluginConfigFromEnv(target any) error

DecodePluginConfigFromEnv decodes the 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 HandshakeConfig

func HandshakeConfig() hplugin.HandshakeConfig

HandshakeConfig returns the shared HashiCorp go-plugin handshake configuration.

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

func ServeModule(m plugin.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.

Types

type Client

type Client interface {
	DetectorDescriptor(context.Context) (*plugin.DetectorDescriptor, error)
	DetectorPackageManagerSupport(context.Context) ([]plugin.PackageManagerSupport, error)
	DetectorReady(context.Context, *plugin.DetectRequest) (*plugin.ReadyResponse, error)
	DetectorApplicable(context.Context, *plugin.DetectRequest) (*plugin.ApplicableResponse, error)
	DetectorInstall(context.Context, *plugin.DetectRequest) (*plugin.InstallResponse, error)
	Detect(context.Context, *plugin.DetectRequest) (*plugin.DetectResponse, error)
	DetectorRemediationHints(context.Context, *plugin.RemediationHintRequest) (*plugin.RemediationHintResponse, error)
	MatcherDescriptor(context.Context) (*plugin.MatcherDescriptor, error)
	MatcherReady(context.Context, *plugin.MatchRequest) (*plugin.ReadyResponse, error)
	MatcherApplicable(context.Context, *plugin.MatchRequest) (*plugin.ApplicableResponse, error)
	Match(context.Context, *plugin.MatchRequest) (*plugin.MatchResponse, error)
	AuditorDescriptor(context.Context) (*plugin.AuditorDescriptor, error)
	AuditorReady(context.Context, *plugin.AuditRequest) (*plugin.ReadyResponse, error)
	AuditorApplicable(context.Context, *plugin.AuditRequest) (*plugin.ApplicableResponse, error)
	Audit(context.Context, *plugin.AuditRequest) (*plugin.AuditResponse, error)
	AnalyzerDescriptor(context.Context) (*plugin.AnalyzerDescriptor, error)
	AnalyzerReady(context.Context, *plugin.AnalyzeRequest) (*plugin.ReadyResponse, error)
	AnalyzerApplicable(context.Context, *plugin.AnalyzeRequest) (*plugin.ApplicableResponse, error)
	Analyze(context.Context, *plugin.AnalyzeRequest) (*plugin.AnalyzeResponse, error)
}

Client is the generic runtime client used by Bomly core.

type DetectorInstaller

type DetectorInstaller interface {
	Install(context.Context, *plugin.DetectRequest) (*plugin.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 ServedAnalyzer

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

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

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, *plugin.RemediationHintRequest) (*plugin.RemediationHintResponse, error)
}

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

type ServedMatcher

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL