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, config decoding from the file named by BOMLY_PLUGIN_CONFIG_FILE, and a process-lifetime scope for OnCleanup) and adapts the component to the wire protocol. It constructs the component under that lifetime rather than the first request's context, and runs its cleanups when the host shuts the plugin down. 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.
The component's lifetime is the process's. Its constructor runs under a context that outlives any one request, and the cleanups it registers through HostContext.OnCleanup run when the host shuts the plugin down: the host's go-plugin client closes the connection, the transport stops serving, and ServeModule closes the scope before it returns -- inside the grace period the client allows before it kills the process. No RPC carries this, so a host of any SDK version gets it.
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.