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
- func ClientPluginMap() map[string]hplugin.Plugin
- func DecodePluginConfigFromEnv(target any) error
- func HandshakeConfig() hplugin.HandshakeConfig
- func RawPluginConfigFromEnv() ([]byte, error)
- func ServeAnalyzer(analyzer ServedAnalyzer)
- func ServeAuditor(auditor ServedAuditor)
- func ServeDetector(detector ServedDetector)
- func ServeMatcher(matcher ServedMatcher)
- func ServeModule(m plugin.Module)
- type Client
- type DetectorInstaller
- type ServedAnalyzer
- type ServedAuditor
- type ServedDetector
- type ServedDetectorRemediationProvider
- type ServedMatcher
Constants ¶
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" )
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 ¶
ClientPluginMap returns the client-side plugin map used by Bomly core.
func DecodePluginConfigFromEnv ¶
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 ¶
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 ¶
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 ¶
type ServedAnalyzer interface {
Descriptor(context.Context) (*plugin.AnalyzerDescriptor, error)
Ready(context.Context, *plugin.AnalyzeRequest) (*plugin.ReadyResponse, error)
Applicable(context.Context, *plugin.AnalyzeRequest) (*plugin.ApplicableResponse, error)
Analyze(context.Context, *plugin.AnalyzeRequest) (*plugin.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) (*plugin.AuditorDescriptor, error)
Ready(context.Context, *plugin.AuditRequest) (*plugin.ReadyResponse, error)
Applicable(context.Context, *plugin.AuditRequest) (*plugin.ApplicableResponse, error)
Audit(context.Context, *plugin.AuditRequest) (*plugin.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) (*plugin.DetectorDescriptor, error)
PackageManagerSupport(context.Context) ([]plugin.PackageManagerSupport, error)
Ready(context.Context, *plugin.DetectRequest) (*plugin.ReadyResponse, error)
Applicable(context.Context, *plugin.DetectRequest) (*plugin.ApplicableResponse, error)
Detect(context.Context, *plugin.DetectRequest) (*plugin.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, *plugin.RemediationHintRequest) (*plugin.RemediationHintResponse, error)
}
ServedDetectorRemediationProvider optionally supplies read-only, package-manager-specific remediation evidence.
type ServedMatcher ¶
type ServedMatcher interface {
Descriptor(context.Context) (*plugin.MatcherDescriptor, error)
Ready(context.Context, *plugin.MatchRequest) (*plugin.ReadyResponse, error)
Applicable(context.Context, *plugin.MatchRequest) (*plugin.ApplicableResponse, error)
Match(context.Context, *plugin.MatchRequest) (*plugin.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.