From a4e8cb25fd0f5ceedb0d170e3113e22c98abbfd5 Mon Sep 17 00:00:00 2001 From: Ahmed ElMallah Date: Sun, 25 Oct 2026 00:37:02 -0700 Subject: [PATCH 01/10] build(deps): adopt bomly-sdk v0.16.0, giving embedded components a lifetime scope v0.15.0 added HostContext.OnCleanup. Each embedded component now gets a plugin.ComponentScope that RegisterModule records before the constructor runs, and Registry.Close ends them newest first with joined errors. Threading the command context and closing the registry at command end follow in this pull request. Co-Authored-By: Claude Opus 5.5 --- go.mod | 2 +- go.sum | 4 +- internal/composition/composition_test.go | 3 +- internal/registry/builder.go | 3 ++ internal/registry/module.go | 51 ++++++++++++++++++++---- 5 files changed, 51 insertions(+), 12 deletions(-) diff --git a/go.mod b/go.mod index 1cf8e892..19617308 100644 --- a/go.mod +++ b/go.mod @@ -14,7 +14,7 @@ require ( github.com/bomly-dev/bomly-plugin-pyreach-analyzer v0.4.0 github.com/bomly-dev/bomly-plugin-scorecard-matcher v0.3.0 github.com/bomly-dev/bomly-plugin-syft-detector v0.6.0 - github.com/bomly-dev/bomly-sdk v0.14.10 + github.com/bomly-dev/bomly-sdk v0.16.0 github.com/charmbracelet/bubbles v1.0.0 github.com/charmbracelet/bubbletea v1.3.10 github.com/charmbracelet/lipgloss v1.1.0 diff --git a/go.sum b/go.sum index a639fad6..05ba7ae5 100644 --- a/go.sum +++ b/go.sum @@ -263,8 +263,8 @@ github.com/bomly-dev/bomly-plugin-scorecard-matcher v0.3.0 h1:CB4M5/N7vR2OlMuxKs github.com/bomly-dev/bomly-plugin-scorecard-matcher v0.3.0/go.mod h1:g62nlreSY249tHBl8uoECIan2FW8r+S1xNFZkbdqSBw= github.com/bomly-dev/bomly-plugin-syft-detector v0.6.0 h1:4U/YOzWujQx1LK+VpPhPEpt2ikwiBciDzaE0V5iNN6M= github.com/bomly-dev/bomly-plugin-syft-detector v0.6.0/go.mod h1:B17C01ssOWdoUGa3geCaouPSge+23QiD2ssFLao0g94= -github.com/bomly-dev/bomly-sdk v0.14.10 h1:ZFb4pXYofXeB6Zd8Rh36vj64X31u9MuD7TB5LwU11hw= -github.com/bomly-dev/bomly-sdk v0.14.10/go.mod h1:XzJZ6B9fNewalouISppzR52Fev4XGIDPElO9OjJTU5M= +github.com/bomly-dev/bomly-sdk v0.16.0 h1:czCVZRiZ2TDGMRQwy1a6jxbS+/3ypoaMYcP0/i7Boo0= +github.com/bomly-dev/bomly-sdk v0.16.0/go.mod h1:XzJZ6B9fNewalouISppzR52Fev4XGIDPElO9OjJTU5M= github.com/bradleyjkemp/cupaloy/v2 v2.8.0 h1:any4BmKE+jGIaMpnU8YgH/I2LPiLBufr6oMMlVBbn9M= github.com/bradleyjkemp/cupaloy/v2 v2.8.0/go.mod h1:bm7JXdkRd4BHJk9HpwqAI8BoAY1lps46Enkdqw6aRX0= github.com/bufbuild/protocompile v0.14.1 h1:iA73zAf/fyljNjQKwYzUHD6AD4R8KMasmwa/FBatYVw= diff --git a/internal/composition/composition_test.go b/internal/composition/composition_test.go index 328c7c99..ff9badf4 100644 --- a/internal/composition/composition_test.go +++ b/internal/composition/composition_test.go @@ -15,7 +15,8 @@ import ( // fakeHost is a minimal plugin.HostContext for construction tests. type fakeHost struct{} -func (fakeHost) Logger() *zap.Logger { return zap.NewNop() } +func (fakeHost) Logger() *zap.Logger { return zap.NewNop() } +func (fakeHost) OnCleanup(func() error) {} func (fakeHost) HTTPClient() *httpkit.ClientProvider { provider, _ := httpkit.NewClientProvider(httpkit.ClientConfig{}) return provider diff --git a/internal/registry/builder.go b/internal/registry/builder.go index 16aa21aa..fc7636bd 100644 --- a/internal/registry/builder.go +++ b/internal/registry/builder.go @@ -127,6 +127,9 @@ type Registry struct { defaultEnabled map[string]bool componentOrigins map[string]plugin.DetectorOrigin httpProvider *httpkit.ClientProvider + // scopes are the lifetimes of the embedded components RegisterModule + // constructed, in construction order; Close ends them. + scopes []*plugin.ComponentScope } // ComponentOptions records Bomly-owned registry behavior that plugin authors diff --git a/internal/registry/module.go b/internal/registry/module.go index d2ebf6ff..efbe0026 100644 --- a/internal/registry/module.go +++ b/internal/registry/module.go @@ -3,6 +3,7 @@ package registry import ( "context" "encoding/json" + "errors" "fmt" "go.uber.org/zap" @@ -19,6 +20,40 @@ type embeddedHostContext struct { registry *Registry kind plugin.PluginKind name string + scope *plugin.ComponentScope +} + +// OnCleanup registers fn on the component's lifetime, which ends when the +// registry is closed. +func (c *embeddedHostContext) OnCleanup(fn func() error) { + c.scope.OnCleanup(fn) +} + +// Close ends the lifetime of every embedded component the registry +// constructed, newest first, running each one's cleanups at most once. Every +// scope is closed even when an earlier one fails; the failures are joined, +// each naming its component. Safe to call more than once. +func (r *Registry) Close() error { + if r == nil { + return nil + } + var errs []error + for i := len(r.scopes) - 1; i >= 0; i-- { + if err := r.scopes[i].Close(); err != nil { + errs = append(errs, err) + } + } + return errors.Join(errs...) +} + +// newEmbeddedHost starts a component lifetime under parent and returns the +// host context that carries it. The scope is recorded before the constructor +// runs, so a constructor that registers a cleanup and then fails is still +// cleaned up when the registry closes. +func (r *Registry) newEmbeddedHost(parent context.Context, kind plugin.PluginKind, name string) *embeddedHostContext { + scope := plugin.NewComponentScope(parent, string(kind)+" "+name) + r.scopes = append(r.scopes, scope) + return &embeddedHostContext{registry: r, kind: kind, name: name, scope: scope} } func (c *embeddedHostContext) Logger() *zap.Logger { @@ -77,29 +112,29 @@ func (r *Registry) RegisterModule(m plugin.Module, opts ComponentOptions) error ctx := context.Background() switch m.Kind { case plugin.PluginKindDetector: - host := &embeddedHostContext{registry: r, kind: m.Kind, name: m.Detector.Descriptor.Name} - detector, err := m.Detector.New(ctx, host) + host := r.newEmbeddedHost(ctx, m.Kind, m.Detector.Descriptor.Name) + detector, err := m.Detector.New(host.scope.Context(), host) if err != nil { return fmt.Errorf("construct detector %q: %w", m.Detector.Descriptor.Name, err) } r.RegisterDetectorWithOptions(detector, opts) case plugin.PluginKindMatcher: - host := &embeddedHostContext{registry: r, kind: m.Kind, name: m.Matcher.Descriptor.Name} - matcher, err := m.Matcher.New(ctx, host) + host := r.newEmbeddedHost(ctx, m.Kind, m.Matcher.Descriptor.Name) + matcher, err := m.Matcher.New(host.scope.Context(), host) if err != nil { return fmt.Errorf("construct matcher %q: %w", m.Matcher.Descriptor.Name, err) } r.RegisterMatcherWithOptions(matcher, opts) case plugin.PluginKindAuditor: - host := &embeddedHostContext{registry: r, kind: m.Kind, name: m.Auditor.Descriptor.Name} - auditor, err := m.Auditor.New(ctx, host) + host := r.newEmbeddedHost(ctx, m.Kind, m.Auditor.Descriptor.Name) + auditor, err := m.Auditor.New(host.scope.Context(), host) if err != nil { return fmt.Errorf("construct auditor %q: %w", m.Auditor.Descriptor.Name, err) } r.RegisterAuditorWithOptions(auditor, opts) case plugin.PluginKindAnalyzer: - host := &embeddedHostContext{registry: r, kind: m.Kind, name: m.Analyzer.Descriptor.Name} - analyzer, err := m.Analyzer.New(ctx, host) + host := r.newEmbeddedHost(ctx, m.Kind, m.Analyzer.Descriptor.Name) + analyzer, err := m.Analyzer.New(host.scope.Context(), host) if err != nil { return fmt.Errorf("construct analyzer %q: %w", m.Analyzer.Descriptor.Name, err) } From d6ac22aa37440a2f4376513a0bfb7138321904ee Mon Sep 17 00:00:00 2001 From: Ahmed ElMallah Date: Sun, 25 Oct 2026 01:04:32 -0700 Subject: [PATCH 02/10] feat(engine): preflight declared component requirements before a stage runs Each stage now compares the requirements a component's descriptor declares (bomly-sdk v0.16.0 plugin.Requirements) with what the host can vouch for: source-tree-v1 for a filesystem or Git target not planned as an SBOM document, dependency-graph-v1 once detection found a dependency node, and vulnerability-records-v1 at analyze and audit once the registry carries a record. A token this host cannot evaluate is never satisfied. Before any stage, an explicitly selected component the plan can never run fails the command with a PreflightError (exit 4) naming the component, the requirement and the remedy. Inside a stage, a component whose requirement the actual data misses is held back through a registry view before Ready is called, with a warning on the stage's channel. Components that declare nothing are untouched, and Ready/Applicable stay authoritative for the rest. engine.go is not touched: the hook lives in pipeline.go around the existing engine calls. Refs bomly-dev/bomly-cli#417 Co-Authored-By: Claude Opus 5.5 --- internal/cli/baseline_cmd.go | 2 +- internal/cli/diff_cmd.go | 2 +- internal/cli/explain_cmd.go | 2 +- internal/cli/pipeline_errors.go | 19 + internal/cli/pipeline_errors_test.go | 20 ++ internal/cli/scan_cmd.go | 2 +- internal/engine/pipeline.go | 36 +- internal/engine/pipeline_explain.go | 5 + internal/engine/preflight.go | 430 +++++++++++++++++++++++ internal/engine/preflight_test.go | 499 +++++++++++++++++++++++++++ internal/registry/view.go | 49 +++ internal/registry/view_test.go | 56 +++ 12 files changed, 1107 insertions(+), 15 deletions(-) create mode 100644 internal/cli/pipeline_errors.go create mode 100644 internal/cli/pipeline_errors_test.go create mode 100644 internal/engine/preflight.go create mode 100644 internal/engine/preflight_test.go create mode 100644 internal/registry/view.go create mode 100644 internal/registry/view_test.go diff --git a/internal/cli/baseline_cmd.go b/internal/cli/baseline_cmd.go index 67022d98..adb866a1 100644 --- a/internal/cli/baseline_cmd.go +++ b/internal/cli/baseline_cmd.go @@ -73,7 +73,7 @@ func newBaselineWriteCmd(action string) *cobra.Command { request := commandCtx.PipelineRequest(model.ScopeUnknown, cmd.ErrOrStderr()) result, err := scanengine.Run(cmd.Context(), pipeline, request) if err != nil { - return exit.ResolutionFailureError(err) + return pipelineFailure(err) } if warningCount := baselineMutationWarningCount(result); warningCount > 0 { return exit.ResolutionFailureError(fmt.Errorf("baseline %s refused because the audit completed with %d degraded-coverage warning(s)", action, warningCount)) diff --git a/internal/cli/diff_cmd.go b/internal/cli/diff_cmd.go index a0ebe57b..7c5c75fb 100644 --- a/internal/cli/diff_cmd.go +++ b/internal/cli/diff_cmd.go @@ -144,7 +144,7 @@ func newDiffCmd() *cobra.Command { }, }) if err != nil { - return exit.ResolutionFailureError(err) + return pipelineFailure(err) } allResults := append(append([]plugin.DetectionResult{}, diffResult.Base.ResolveResults...), diffResult.Head.ResolveResults...) diff --git a/internal/cli/explain_cmd.go b/internal/cli/explain_cmd.go index 27a7298e..2e81d1de 100644 --- a/internal/cli/explain_cmd.go +++ b/internal/cli/explain_cmd.go @@ -85,7 +85,7 @@ func newExplainCmd() *cobra.Command { Pipeline: pipeReq, }) if err != nil { - return exit.ResolutionFailureError(err) + return pipelineFailure(err) } resolved := explainResult.ResolveResults diff --git a/internal/cli/pipeline_errors.go b/internal/cli/pipeline_errors.go new file mode 100644 index 00000000..d56e748a --- /dev/null +++ b/internal/cli/pipeline_errors.go @@ -0,0 +1,19 @@ +package cli + +import ( + "errors" + + "github.com/bomly-dev/bomly-cli/internal/cli/exit" + "github.com/bomly-dev/bomly-cli/internal/engine" +) + +// pipelineFailure maps a pipeline error to its exit code. A selection the +// plan can never run -- an explicitly selected component whose declared +// requirements the target cannot meet -- is invalid input; anything else +// failed while resolving. +func pipelineFailure(err error) error { + if _, ok := errors.AsType[*engine.PreflightError](err); ok { + return exit.InvalidInputError("%v", err) + } + return exit.ResolutionFailureError(err) +} diff --git a/internal/cli/pipeline_errors_test.go b/internal/cli/pipeline_errors_test.go new file mode 100644 index 00000000..6c66a358 --- /dev/null +++ b/internal/cli/pipeline_errors_test.go @@ -0,0 +1,20 @@ +package cli + +import ( + "errors" + "fmt" + "testing" + + "github.com/bomly-dev/bomly-cli/internal/cli/exit" + "github.com/bomly-dev/bomly-cli/internal/engine" +) + +func TestPipelineFailureSeparatesImpossibleSelectionsFromResolutionFailures(t *testing.T) { + preflight := &engine.PreflightError{Issues: []engine.PreflightIssue{{Component: "reach", Requirement: "source-tree-v1"}}} + if got, want := exit.Code(pipelineFailure(fmt.Errorf("base pipeline: %w", preflight))), exit.Code(exit.InvalidInputError("x")); got != want { + t.Fatalf("a selection the plan cannot run exits %d, want the invalid-input code %d", got, want) + } + if got, want := exit.Code(pipelineFailure(errors.New("dependency resolution: boom"))), exit.Code(exit.ResolutionFailureError(errors.New("x"))); got != want { + t.Fatalf("a resolution failure exits %d, want %d", got, want) + } +} diff --git a/internal/cli/scan_cmd.go b/internal/cli/scan_cmd.go index 0e17b48c..2e82a5e6 100644 --- a/internal/cli/scan_cmd.go +++ b/internal/cli/scan_cmd.go @@ -87,7 +87,7 @@ func newScanCmd() *cobra.Command { pipeReq.Progress = prog pipeResult, err := scanengine.Run(cmd.Context(), pipeline, pipeReq) if err != nil { - return exit.ResolutionFailureError(err) + return pipelineFailure(err) } resolved := pipeResult.ResolveResults detectionChildren := detectorProgressChildren(resolved) diff --git a/internal/engine/pipeline.go b/internal/engine/pipeline.go index c5ca48f6..f63c389b 100644 --- a/internal/engine/pipeline.go +++ b/internal/engine/pipeline.go @@ -51,6 +51,9 @@ func (p *Pipeline) Run(ctx context.Context, req PipelineRequest) (PipelineResult // before policy evaluation. func (p *Pipeline) RunPreAudit(ctx context.Context, req PipelineRequest) (PipelineResult, error) { result := PipelineResult{} + if err := p.preflightPlan(req); err != nil { + return result, err + } if err := p.runDetect(ctx, &result, req); err != nil { return result, err } @@ -136,9 +139,14 @@ func acceptedFindingCount(findings []model.Finding) int { // consolidates them into the single graph and package registry the rest of the // pipeline operates on. Consolidation is the tail of detection, not a separate stage. func (p *Pipeline) runDetect(ctx context.Context, result *PipelineResult, req PipelineRequest) error { - if err := p.runResolve(ctx, result, req); err != nil { + stage, issues := p.preflightStage(StageDetect, req, nil, nil) + if err := stage.runResolve(ctx, result, req); err != nil { + if len(issues) > 0 { + return fmt.Errorf("%w (%s)", err, preflightSummary(issues)) + } return err } + result.DetectorWarnings = append(result.DetectorWarnings, detectorPreflightWarnings(issues)...) return p.runConsolidate(result) } @@ -500,7 +508,9 @@ func (p *Pipeline) analyze(ctx context.Context, result *PipelineResult, req Pipe AnalyzerFilter: req.AnalyzerFilter, Stderr: req.Stderr, } - analyzeResult, err := p.engine.Analyze(ctx, aReq) + stage, issues := p.preflightStage(StageAnalyze, req, result.Graph, result.Registry) + result.AnalyzeWarnings = append(result.AnalyzeWarnings, preflightWarnings(issues)...) + analyzeResult, err := stage.engine.Analyze(ctx, aReq) result.AnalyzerRuns = analyzeResult.AnalyzerRuns if len(analyzeResult.AnalyzerStats) > 0 { result.AnalyzerStats = analyzeResult.AnalyzerStats @@ -509,7 +519,7 @@ func (p *Pipeline) analyze(ctx context.Context, result *PipelineResult, req Pipe result.Registry = analyzeResult.Registry } if err != nil { - result.AnalyzeWarnings = PipelineWarningsFromError(err, "analyzer") + result.AnalyzeWarnings = append(result.AnalyzeWarnings, PipelineWarningsFromError(err, "analyzer")...) p.Logger.Warn("pipeline: reachability analysis errors", zap.Error(err)) } } @@ -538,7 +548,9 @@ func (p *Pipeline) match(ctx context.Context, result *PipelineResult, req Pipeli MatcherFilter: req.MatcherFilter, Stderr: req.Stderr, } - matchResult, err := p.engine.Match(ctx, mReq) + stage, issues := p.preflightStage(StageMatch, req, result.Graph, result.Registry) + result.MatchWarnings = append(result.MatchWarnings, preflightWarnings(issues)...) + matchResult, err := stage.engine.Match(ctx, mReq) result.MatcherStats = matchResult.MatcherStats if matchResult.Registry != nil { result.Registry = matchResult.Registry @@ -548,7 +560,7 @@ func (p *Pipeline) match(ctx context.Context, result *PipelineResult, req Pipeli zap.Int("records_removed", matchResult.VulnerabilitiesConsolidated)) } if err != nil { - result.MatchWarnings = PipelineWarningsFromError(err, "matcher") + result.MatchWarnings = append(result.MatchWarnings, PipelineWarningsFromError(err, "matcher")...) p.Logger.Warn("pipeline: matcher enrichment error", zap.Error(err)) } } @@ -564,10 +576,11 @@ func (p *Pipeline) audit(ctx context.Context, g *model.Graph, registry *model.Pa AuditorFilter: req.AuditorFilter, Stderr: req.Stderr, } - result, err := p.engine.Audit(ctx, auditReq) - var warnings []PipelineWarning + stage, issues := p.preflightStage(StageAudit, req, g, registry) + warnings := preflightWarnings(issues) + result, err := stage.engine.Audit(ctx, auditReq) if err != nil { - warnings = PipelineWarningsFromError(err, "auditor") + warnings = append(warnings, PipelineWarningsFromError(err, "auditor")...) p.Logger.Warn("pipeline: audit errors", zap.Error(err)) } return result, warnings @@ -587,12 +600,13 @@ func (p *Pipeline) auditComponent(ctx context.Context, g *model.Graph, registry AuditorFilter: req.AuditorFilter, Stderr: req.Stderr, } - result, err := p.engine.Audit(ctx, auditReq) + stage, issues := p.preflightStage(StageAudit, req, g, registry) + warnings := preflightWarnings(issues) + result, err := stage.engine.Audit(ctx, auditReq) result.Findings = DeduplicateFindings(result.Findings) result.Findings = p.applyFindingPolicy(ctx, result.Findings, registry, req) - var warnings []PipelineWarning if err != nil { - warnings = PipelineWarningsFromError(err, "auditor") + warnings = append(warnings, PipelineWarningsFromError(err, "auditor")...) p.Logger.Warn("pipeline: component audit errors", zap.Error(err)) } return result, warnings diff --git a/internal/engine/pipeline_explain.go b/internal/engine/pipeline_explain.go index e70d75a2..d5ba948a 100644 --- a/internal/engine/pipeline_explain.go +++ b/internal/engine/pipeline_explain.go @@ -43,6 +43,11 @@ func (p *Pipeline) RunExplain(ctx context.Context, req ExplainRequest) (ExplainR pipeReq.AuditEnabled = false base := PipelineResult{} + // Planned with the caller's audit setting: explain audits the queried + // component itself, so an explicitly selected auditor is still in its plan. + if err := p.preflightPlan(req.Pipeline); err != nil { + return ExplainResult{PipelineResult: base}, err + } if err := p.runDetect(ctx, &base, pipeReq); err != nil { return ExplainResult{PipelineResult: base}, err } diff --git a/internal/engine/preflight.go b/internal/engine/preflight.go new file mode 100644 index 00000000..bed42a10 --- /dev/null +++ b/internal/engine/preflight.go @@ -0,0 +1,430 @@ +package engine + +import ( + "fmt" + "slices" + "strings" + + "go.uber.org/zap" + + "github.com/bomly-dev/bomly-sdk/model" + "github.com/bomly-dev/bomly-sdk/plugin" +) + +// Preflight evaluates the requirements a component descriptor declares +// (plugin.Requirements, the SDK's vocabulary) against what the host can vouch +// for at the stage the component runs in, before its Ready, Applicable or +// action method is called. It never reorders the fixed pipeline and never +// looks a provider up by name: a requirement names data, and the only +// question asked is whether that data exists at that point. A component that +// declares nothing is legacy and passes untouched. ADR-0051 records the rules. + +// PipelineStage names one stage of the fixed pipeline. +type PipelineStage string + +// The stages, in the order the pipeline runs them. +const ( + StageDetect PipelineStage = "detect" + StageMatch PipelineStage = "match" + StageAnalyze PipelineStage = "analyze" + StageAudit PipelineStage = "audit" +) + +// stageKinds maps each stage to the component kind that runs in it. +var stageKinds = map[PipelineStage]plugin.PluginKind{ + StageDetect: plugin.PluginKindDetector, + StageMatch: plugin.PluginKindMatcher, + StageAnalyze: plugin.PluginKindAnalyzer, + StageAudit: plugin.PluginKindAuditor, +} + +// hostRequirements is the vocabulary this host knows how to evaluate. A +// token outside it -- unknown to the SDK, or known to a newer SDK than this +// evaluator was written for -- is never available, so it always comes back +// unsatisfied. +var hostRequirements = []plugin.Requirement{ + plugin.RequirementSourceTree, + plugin.RequirementDependencyGraph, + plugin.RequirementVulnerabilityRecords, +} + +// Evaluates reports whether this host can vouch for requirement at all. A +// token it cannot evaluate is never satisfied, whatever the target. +func Evaluates(requirement plugin.Requirement) bool { + return slices.Contains(hostRequirements, requirement) +} + +// PreflightIssue is one declared requirement the host cannot vouch for at +// the stage the component runs in. +type PreflightIssue struct { + Kind plugin.PluginKind + Component string + Stage PipelineStage + Requirement plugin.Requirement + // Explicit reports whether the user's selection is why the component is + // in the plan; see selectedExplicitly. + Explicit bool + // Satisfy says what is missing and what would supply it. + Satisfy string +} + +// String renders the issue as one actionable sentence. +func (i PreflightIssue) String() string { + return fmt.Sprintf("%s %s requires %s: %s", i.Kind, i.Component, i.Requirement, i.Satisfy) +} + +// PreflightError reports explicitly selected components the plan can never +// run. It is returned before any stage starts. +type PreflightError struct { + Issues []PreflightIssue +} + +// Error lists every issue, so one run reports all of them. +func (e *PreflightError) Error() string { + return "selected components cannot run: " + joinIssues(e.Issues) +} + +func joinIssues(issues []PreflightIssue) string { + reasons := make([]string, 0, len(issues)) + for _, issue := range issues { + reasons = append(reasons, issue.String()) + } + return strings.Join(reasons, "; ") +} + +// preflightCandidate is one component a stage would run. +type preflightCandidate struct { + kind plugin.PluginKind + name string + requires plugin.Requirements + explicit bool +} + +// preflightFacts is what the host knows about the run when it plans a +// stage. +type preflightFacts struct { + stage PipelineStage + // planning is set before any stage has run. Requirements that depend on + // what an earlier stage produces are then taken as producible; the stage + // checks them again against the data it actually receives. + planning bool + target targetShape + matchStage bool + dependencyNodes bool + vulnerabilityRecords bool +} + +// targetShape says whether the execution target is a source tree and, when +// it is not, what it is instead. +type targetShape struct { + sourceTree bool + description string +} + +// describeTarget classifies the request's target. A filesystem path or a Git +// checkout is a source tree unless discovery planned it as an SBOM document; +// a container image, and a target whose kind is not recorded, is not. +func describeTarget(req PipelineRequest) targetShape { + for _, sub := range req.Subprojects { + if sub.PrimaryPackageManager() == model.PackageManagerSBOM { + return targetShape{description: "an SBOM document"} + } + } + switch req.ExecutionTarget.Kind { + case plugin.ExecutionTargetFilesystem, plugin.ExecutionTargetGitRepository: + return targetShape{sourceTree: true} + case plugin.ExecutionTargetContainerImage: + return targetShape{description: "a container image"} + default: + return targetShape{description: "an input of unrecorded kind"} + } +} + +// available returns the requirements the host can vouch for under facts. +func (f preflightFacts) available() []plugin.Requirement { + var out []plugin.Requirement + if f.target.sourceTree { + out = append(out, plugin.RequirementSourceTree) + } + // Detection is the stage that produces the graph. + if f.stage != StageDetect && (f.planning || f.dependencyNodes) { + out = append(out, plugin.RequirementDependencyGraph) + } + // Matchers supply vulnerability records, so they exist only for the + // stages after matching. Which matcher supplies them is not asked: the + // registry either carries a record or it does not. + if (f.stage == StageAnalyze || f.stage == StageAudit) && (f.planning || f.vulnerabilityRecords) { + out = append(out, plugin.RequirementVulnerabilityRecords) + } + return out +} + +// issues returns one issue per requirement candidate declares that facts +// cannot vouch for. +func (f preflightFacts) issues(candidate preflightCandidate) []PreflightIssue { + unmet := candidate.requires.Unsatisfied(f.available()) + if len(unmet) == 0 { + return nil + } + issues := make([]PreflightIssue, 0, len(unmet)) + for _, requirement := range unmet { + issues = append(issues, PreflightIssue{ + Kind: candidate.kind, + Component: candidate.name, + Stage: f.stage, + Requirement: requirement, + Explicit: candidate.explicit, + Satisfy: f.satisfy(requirement), + }) + } + return issues +} + +// satisfy explains why requirement is unmet and what would meet it. +func (f preflightFacts) satisfy(requirement plugin.Requirement) string { + if !Evaluates(requirement) { + return "this version of Bomly does not know this requirement; upgrade Bomly, or use a component version that does not declare it" + } + switch requirement { + case plugin.RequirementSourceTree: + return fmt.Sprintf("the target is %s, not a source tree; scan a directory with --path or a Git repository with --url", f.target.description) + case plugin.RequirementDependencyGraph: + if f.stage == StageDetect { + return "detection is the stage that produces the dependency graph, so a detector cannot require one" + } + return "detection found no dependencies in the target" + default: // plugin.RequirementVulnerabilityRecords + switch { + case f.stage == StageDetect || f.stage == StageMatch: + return "matchers supply vulnerability records, so only an analyzer or an auditor can require them" + case !f.matchStage: + return "no matcher ran; add --enrich so a vulnerability matcher can supply them" + default: + return "no package carries a vulnerability record after enrichment" + } + } +} + +// plannedStages returns the stages req runs, in pipeline order. +func plannedStages(req PipelineRequest) []PipelineStage { + stages := []PipelineStage{StageDetect} + if req.EnrichEnabled || req.MatchEnabled { + stages = append(stages, StageMatch) + } + if req.AnalyzeReachabilityEnabled { + stages = append(stages, StageAnalyze) + } + if req.AuditEnabled { + stages = append(stages, StageAudit) + } + return stages +} + +// preflightPlan fails the run, before any stage starts, when an explicitly +// selected component declares a requirement the plan can never satisfy: a +// source tree the target is not, a token this host does not know, or data +// no earlier stage produces. A default-selected component is left to the +// stage, which skips it with a diagnostic. +func (p *Pipeline) preflightPlan(req PipelineRequest) error { + target := describeTarget(req) + var issues []PreflightIssue + for _, stage := range plannedStages(req) { + facts := preflightFacts{stage: stage, planning: true, target: target, matchStage: req.EnrichEnabled || req.MatchEnabled} + for _, candidate := range p.stageCandidates(stage, req) { + if candidate.explicit { + issues = append(issues, facts.issues(candidate)...) + } + } + } + if len(issues) == 0 { + return nil + } + for _, issue := range issues { + p.Logger.Warn("pipeline: selected component cannot run", + zap.String("kind", string(issue.Kind)), + zap.String("component", issue.Component), + zap.String("stage", string(issue.Stage)), + zap.String("requirement", string(issue.Requirement)), + zap.String("reason", issue.Satisfy)) + } + return &PreflightError{Issues: issues} +} + +// preflightStage evaluates the components stage would run against the data +// the stage actually receives. It returns the pipeline the stage runs on -- +// p itself when nothing is held back, otherwise a view whose registry leaves +// the held-back components out -- and one issue per unmet requirement. +// Components that pass still go through Ready and Applicable as before. +func (p *Pipeline) preflightStage(stage PipelineStage, req PipelineRequest, graph *model.Graph, registry *model.PackageRegistry) (*Pipeline, []PreflightIssue) { + facts := preflightFacts{ + stage: stage, + target: describeTarget(req), + matchStage: req.EnrichEnabled || req.MatchEnabled, + dependencyNodes: hasDependencyNode(graph), + vulnerabilityRecords: hasVulnerabilityRecord(registry), + } + candidates := p.stageCandidates(stage, req) + var issues []PreflightIssue + var skipped []string + declared := 0 + for _, candidate := range candidates { + if len(candidate.requires) > 0 { + declared++ + } + found := facts.issues(candidate) + if len(found) == 0 { + continue + } + issues = append(issues, found...) + skipped = append(skipped, candidate.name) + for _, issue := range found { + p.Logger.Warn("pipeline: component skipped by preflight", + zap.String("kind", string(issue.Kind)), + zap.String("component", issue.Component), + zap.String("stage", string(issue.Stage)), + zap.String("requirement", string(issue.Requirement)), + zap.Bool("explicit", issue.Explicit), + zap.String("reason", issue.Satisfy)) + } + } + p.Logger.Debug("pipeline: preflight evaluated", + zap.String("stage", string(stage)), + zap.Int("components", len(candidates)), + zap.Int("declaring_requirements", declared), + zap.Strings("skipped", skipped)) + if len(skipped) == 0 { + return p, nil + } + view := &Registry{Registry: p.Registry.Without(stageKinds[stage], skipped)} + return &Pipeline{Registry: view, Logger: p.Logger, engine: NewEngine(view)}, issues +} + +// stageCandidates lists the components stage would run for req, through the +// same registry selection the stage itself uses, so preflight sees exactly +// the plan the filters, defaults and detector chains produce. +func (p *Pipeline) stageCandidates(stage PipelineStage, req PipelineRequest) []preflightCandidate { + reg := p.Registry + kind := stageKinds[stage] + var candidates []preflightCandidate + add := func(name string, requires plugin.Requirements, include, exclude []string, includes func(string) bool) { + explicit := selectedExplicitly(include, exclude, includes, name, reg.DefaultEnabled(kind, name)) + candidates = append(candidates, preflightCandidate{kind: kind, name: name, requires: requires, explicit: explicit}) + } + switch stage { + case StageDetect: + filter := req.DetectorFilter + seen := make(map[string]struct{}) + for _, sub := range req.Subprojects { + planned := reg.PlannedDetectors(plugin.DetectionRequest{ + DetectorFilter: filter, + Ecosystem: sub.Ecosystem, + PackageManager: sub.PrimaryPackageManager(), + }, sub.PlannedDetectors) + for _, detector := range planned { + descriptor := detector.Descriptor() + if _, ok := seen[descriptor.Name]; ok { + continue + } + seen[descriptor.Name] = struct{}{} + add(descriptor.Name, descriptor.Requires, filter.Include, filter.Exclude, filter.Includes) + } + } + case StageMatch: + filter := req.MatcherFilter + for _, matcher := range reg.Matchers(plugin.MatchRequest{MatcherFilter: filter}) { + descriptor := matcher.Descriptor() + add(descriptor.Name, descriptor.Requires, filter.Include, filter.Exclude, filter.Includes) + } + case StageAnalyze: + filter := req.AnalyzerFilter + for _, analyzer := range reg.Analyzers(plugin.AnalyzeRequest{AnalyzerFilter: filter}) { + descriptor := analyzer.Descriptor() + add(descriptor.Name, descriptor.Requires, filter.Include, filter.Exclude, filter.Includes) + } + case StageAudit: + filter := req.AuditorFilter + for _, auditor := range reg.Auditors(plugin.AuditRequest{AuditorFilter: filter}) { + descriptor := auditor.Descriptor() + add(descriptor.Name, descriptor.Requires, filter.Include, filter.Exclude, filter.Includes) + } + } + return candidates +} + +// selectedExplicitly reports whether the user's selection is why a component +// is in the plan: it is named in a plain selector list, or it is off by +// default and a "+name" selector added it. The operator form resolves to an +// exclude-only filter, so a default-off component that survives one was +// added by name. A default-on component is implicit even when "+name" +// repeats it, because it would have run anyway. +func selectedExplicitly(include, exclude []string, includes func(string) bool, name string, defaultEnabled bool) bool { + if len(include) > 0 { + return includes(name) + } + return len(exclude) > 0 && !defaultEnabled +} + +func hasDependencyNode(graph *model.Graph) bool { + if graph == nil { + return false + } + found := false + graph.WalkNodes(func(node model.GraphNode) bool { + _, found = node.(*model.DependencyNode) + return !found + }) + return found +} + +func hasVulnerabilityRecord(registry *model.PackageRegistry) bool { + if registry == nil { + return false + } + for _, pkg := range registry.All() { + if pkg != nil && len(pkg.Vulnerabilities) > 0 { + return true + } + } + return false +} + +// preflightWarnings renders stage issues on the stage's warning channel, the +// one a default-verbosity run shows. +func preflightWarnings(issues []PreflightIssue) []PipelineWarning { + if len(issues) == 0 { + return nil + } + warnings := make([]PipelineWarning, 0, len(issues)) + for _, issue := range issues { + warnings = append(warnings, PipelineWarning{Source: issue.Component, Message: preflightSkipMessage(issue)}) + } + return warnings +} + +// detectorPreflightWarnings renders detector issues as typed detector +// warnings. A held-back detector means its subproject was resolved by a +// later link of its chain or not at all, so the warning degrades coverage. +func detectorPreflightWarnings(issues []PreflightIssue) []plugin.DetectorWarning { + if len(issues) == 0 { + return nil + } + warnings := make([]plugin.DetectorWarning, 0, len(issues)) + for _, issue := range issues { + warnings = append(warnings, plugin.DetectorWarning{ + Type: plugin.DetectorWarningResolutionFailure, + Source: issue.Component, + Message: preflightSkipMessage(issue), + }) + } + return warnings +} + +func preflightSkipMessage(issue PreflightIssue) string { + return fmt.Sprintf("skipped: requires %s; %s", issue.Requirement, issue.Satisfy) +} + +// preflightSummary joins issues into one clause for an error that a held-back +// component may explain. +func preflightSummary(issues []PreflightIssue) string { + return "preflight held back " + joinIssues(issues) +} diff --git a/internal/engine/preflight_test.go b/internal/engine/preflight_test.go new file mode 100644 index 00000000..a4b12cee --- /dev/null +++ b/internal/engine/preflight_test.go @@ -0,0 +1,499 @@ +package engine + +import ( + "context" + "errors" + "strings" + "testing" + + "github.com/bomly-dev/bomly-cli/internal/testnodes" + "go.uber.org/zap" + + "github.com/bomly-dev/bomly-sdk/model" + "github.com/bomly-dev/bomly-sdk/plugin" +) + +// calls records which contract methods the pipeline reached on a component, +// so a test can prove preflight held it back before Ready. +type calls struct{ ready, applicable, action int } + +type preflightMatcher struct { + descriptor plugin.MatcherDescriptor + vulnerabilities bool + calls *calls +} + +func (m preflightMatcher) Descriptor() plugin.MatcherDescriptor { return m.descriptor } +func (m preflightMatcher) Ready(context.Context, plugin.MatchRequest) error { + m.calls.ready++ + return nil +} +func (m preflightMatcher) Applicable(context.Context, plugin.MatchRequest) (bool, error) { + m.calls.applicable++ + return true, nil +} +func (m preflightMatcher) Match(_ context.Context, req plugin.MatchRequest) (plugin.MatchResult, error) { + m.calls.action++ + if m.vulnerabilities { + for _, pkg := range req.Registry.All() { + pkg.Vulnerabilities = append(pkg.Vulnerabilities, model.Vulnerability{ID: "GHSA-test-0001"}) + } + } + return plugin.MatchResult{Registry: req.Registry}, nil +} + +type preflightAnalyzer struct { + descriptor plugin.AnalyzerDescriptor + applicable bool + calls *calls +} + +func (a preflightAnalyzer) Descriptor() plugin.AnalyzerDescriptor { return a.descriptor } +func (a preflightAnalyzer) Ready(context.Context, plugin.AnalyzeRequest) error { + a.calls.ready++ + return nil +} +func (a preflightAnalyzer) Applicable(context.Context, plugin.AnalyzeRequest) (bool, error) { + a.calls.applicable++ + return a.applicable, nil +} +func (a preflightAnalyzer) Analyze(_ context.Context, req plugin.AnalyzeRequest) (plugin.AnalyzeResult, error) { + a.calls.action++ + return plugin.AnalyzeResult{Registry: req.Registry}, nil +} + +type preflightAuditor struct { + descriptor plugin.AuditorDescriptor + calls *calls +} + +func (a preflightAuditor) Descriptor() plugin.AuditorDescriptor { return a.descriptor } +func (a preflightAuditor) Ready(context.Context, plugin.AuditRequest) error { + a.calls.ready++ + return nil +} +func (a preflightAuditor) Applicable(context.Context, plugin.AuditRequest) (bool, error) { + a.calls.applicable++ + return true, nil +} +func (a preflightAuditor) Audit(context.Context, plugin.AuditRequest) (plugin.AuditResult, error) { + a.calls.action++ + return plugin.AuditResult{}, nil +} + +// preflightGraph is a two-dependency graph, so dependency-graph-v1 holds. +func preflightGraph(t *testing.T) *model.Graph { + t.Helper() + g := model.New() + for _, label := range []string{"app@1.0.0", "react@18.2.0"} { + if err := g.AddNode(testnodes.Ref(strings.Split(label, "@")[0], strings.Split(label, "@")[1])); err != nil { + t.Fatalf("add node: %v", err) + } + } + if err := g.AddEdge(testnodes.ID(g, "app@1.0.0"), testnodes.ID(g, "react@18.2.0")); err != nil { + t.Fatalf("add edge: %v", err) + } + return g +} + +// preflightScenario builds a registry with one npm detector, plus req for a +// filesystem target. Tests swap the target or add components. +func preflightScenario(t *testing.T, graph *model.Graph) (*Registry, PipelineRequest) { + t.Helper() + registry := newTestRegistry() + registry.registerDetector(fakeDetector{ + descriptor: DetectorDescriptor{Name: "npm-detector", SupportedEcosystems: []Ecosystem{EcosystemNPM}, SupportedManagers: []PackageManager{PackageManagerNPM}}, + result: ResolveGraphResult{Graphs: SingleGraphContainer(graph, model.ManifestMetadata{Path: "package-lock.json", Kind: "package-lock.json"})}, + }) + target := ExecutionTarget{Kind: ExecutionTargetFilesystem, Location: "/repo"} + return registry, PipelineRequest{ + ExecutionTarget: target, + Subprojects: []Subproject{{ + ExecutionTarget: target, + RelativePath: ".", + DetectedPackageManagers: []PackageManager{PackageManagerNPM}, + Ecosystem: EcosystemNPM, + }}, + } +} + +// sbomTarget replaces req's target with an ingested SBOM document, planned +// the way --sbom plans it, and registers a detector for it. +func sbomTarget(registry *Registry, req *PipelineRequest, graph *model.Graph) { + registry.registerDetector(fakeDetector{ + descriptor: DetectorDescriptor{Name: "sbom-detector", SupportedEcosystems: []Ecosystem{EcosystemSBOM}, SupportedManagers: []PackageManager{PackageManagerSBOM}}, + result: ResolveGraphResult{Graphs: SingleGraphContainer(graph, model.ManifestMetadata{Path: "bom.cdx.json", Kind: "cyclonedx"})}, + }) + target := ExecutionTarget{Kind: ExecutionTargetFilesystem, Location: "/repo/bom.cdx.json"} + req.ExecutionTarget = target + req.Subprojects = []Subproject{{ + ExecutionTarget: target, + RelativePath: ".", + DetectedPackageManagers: []PackageManager{PackageManagerSBOM}, + Ecosystem: EcosystemSBOM, + }} +} + +func requires(tokens ...plugin.Requirement) plugin.Requirements { return tokens } + +func TestPreflight_LegacyComponentsRunAsBeforeOnAnyTarget(t *testing.T) { + graph := preflightGraph(t) + registry, req := preflightScenario(t, graph) + sbomTarget(registry, &req, graph) + matcher, analyzer, auditor := &calls{}, &calls{}, &calls{} + registry.registerMatcher(preflightMatcher{descriptor: plugin.MatcherDescriptor{Name: "legacy-matcher"}, calls: matcher}) + registry.RegisterAnalyzer(preflightAnalyzer{descriptor: plugin.AnalyzerDescriptor{Name: "legacy-analyzer"}, applicable: true, calls: analyzer}) + registry.registerAuditor(preflightAuditor{descriptor: plugin.AuditorDescriptor{Name: "legacy-auditor"}, calls: auditor}) + req.EnrichEnabled, req.AnalyzeReachabilityEnabled, req.AuditEnabled = true, true, true + + result, err := NewPipeline(registry, zap.NewNop()).Run(context.Background(), req) + if err != nil { + t.Fatalf("Run() error = %v", err) + } + for name, got := range map[string]*calls{"matcher": matcher, "analyzer": analyzer, "auditor": auditor} { + if got.ready != 1 || got.applicable != 1 || got.action != 1 { + t.Errorf("%s: a component that declares nothing must run exactly as before, got %+v", name, *got) + } + } + if len(result.MatchWarnings)+len(result.AnalyzeWarnings)+len(result.AuditWarnings) != 0 { + t.Errorf("legacy components must raise no preflight warning, got %v %v %v", result.MatchWarnings, result.AnalyzeWarnings, result.AuditWarnings) + } +} + +func TestPreflight_SatisfiedRequirementsStillGoThroughReadyAndApplicable(t *testing.T) { + registry, req := preflightScenario(t, preflightGraph(t)) + matcher, reachable, notApplicable := &calls{}, &calls{}, &calls{} + registry.registerMatcher(preflightMatcher{ + descriptor: plugin.MatcherDescriptor{Name: "vuln-matcher", Requires: requires(plugin.RequirementDependencyGraph)}, + vulnerabilities: true, + calls: matcher, + }) + every := requires(plugin.RequirementSourceTree, plugin.RequirementDependencyGraph, plugin.RequirementVulnerabilityRecords) + registry.RegisterAnalyzer(preflightAnalyzer{descriptor: plugin.AnalyzerDescriptor{Name: "reach", Requires: every}, applicable: true, calls: reachable}) + registry.RegisterAnalyzer(preflightAnalyzer{descriptor: plugin.AnalyzerDescriptor{Name: "picky", Requires: every}, applicable: false, calls: notApplicable}) + req.EnrichEnabled, req.AnalyzeReachabilityEnabled = true, true + + result, err := NewPipeline(registry, zap.NewNop()).Run(context.Background(), req) + if err != nil { + t.Fatalf("Run() error = %v", err) + } + if matcher.action != 1 || reachable.action != 1 { + t.Fatalf("satisfied components must run: matcher %+v, analyzer %+v", *matcher, *reachable) + } + // Applicable stays authoritative after preflight passes. + if notApplicable.ready != 1 || notApplicable.applicable != 1 || notApplicable.action != 0 { + t.Fatalf("a component that passes preflight must still be asked Applicable and obeyed, got %+v", *notApplicable) + } + if len(result.AnalyzeWarnings) != 0 { + t.Fatalf("no requirement was unmet, got warnings %v", result.AnalyzeWarnings) + } +} + +func TestPreflight_DefaultSelectedComponentIsSkippedWithADiagnostic(t *testing.T) { + cases := []struct { + name string + target func(*Registry, *PipelineRequest, *model.Graph) + want string + }{ + {"SBOM document", sbomTarget, "the target is an SBOM document, not a source tree"}, + {"container image", func(_ *Registry, req *PipelineRequest, _ *model.Graph) { + req.ExecutionTarget = ExecutionTarget{Kind: ExecutionTargetContainerImage, Location: "alpine:3.20"} + }, "the target is a container image, not a source tree"}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + graph := preflightGraph(t) + registry, req := preflightScenario(t, graph) + tc.target(registry, &req, graph) + analyzer := &calls{} + registry.RegisterAnalyzer(preflightAnalyzer{descriptor: plugin.AnalyzerDescriptor{Name: "reach", Requires: requires(plugin.RequirementSourceTree)}, applicable: true, calls: analyzer}) + req.AnalyzeReachabilityEnabled = true + + result, err := NewPipeline(registry, zap.NewNop()).Run(context.Background(), req) + if err != nil { + t.Fatalf("a default-selected component must not fail the run, got %v", err) + } + if *analyzer != (calls{}) { + t.Fatalf("preflight must hold the component back before Ready, got %+v", *analyzer) + } + if len(result.AnalyzeWarnings) != 1 { + t.Fatalf("expected one diagnostic, got %v", result.AnalyzeWarnings) + } + warning := result.AnalyzeWarnings[0] + if warning.Source != "reach" || !strings.Contains(warning.Message, "requires source-tree-v1") || !strings.Contains(warning.Message, tc.want) { + t.Fatalf("diagnostic must name the component, the requirement and what is missing, got %+v", warning) + } + }) + } +} + +func TestPreflight_ExplicitlySelectedComponentFailsBeforeAnyStage(t *testing.T) { + graph := preflightGraph(t) + registry, req := preflightScenario(t, graph) + sbomTarget(registry, &req, graph) + detected := false + registry.registerDetector(fakeDetector{ + descriptor: DetectorDescriptor{Name: "watch", SupportedEcosystems: []Ecosystem{EcosystemSBOM}, SupportedManagers: []PackageManager{PackageManagerSBOM}}, + onResolve: func(ResolveGraphRequest) { detected = true }, + }) + req.Subprojects[0].PlannedDetectors = []string{"watch", "sbom-detector"} + analyzer := &calls{} + registry.RegisterAnalyzer(preflightAnalyzer{descriptor: plugin.AnalyzerDescriptor{Name: "reach", Requires: requires(plugin.RequirementSourceTree)}, applicable: true, calls: analyzer}) + req.AnalyzeReachabilityEnabled = true + req.AnalyzerFilter = plugin.AnalyzerFilter{Include: []string{"reach"}} + + _, err := NewPipeline(registry, zap.NewNop()).Run(context.Background(), req) + preflight, ok := errors.AsType[*PreflightError](err) + if !ok { + t.Fatalf("an explicitly selected component that can never run must fail the run, got %v", err) + } + if detected || *analyzer != (calls{}) { + t.Fatalf("the plan must fail before any stage runs: detected=%v analyzer=%+v", detected, *analyzer) + } + want := PreflightIssue{ + Kind: plugin.PluginKindAnalyzer, + Component: "reach", + Stage: StageAnalyze, + Requirement: plugin.RequirementSourceTree, + Explicit: true, + Satisfy: "the target is an SBOM document, not a source tree; scan a directory with --path or a Git repository with --url", + } + if len(preflight.Issues) != 1 || preflight.Issues[0] != want { + t.Fatalf("issues = %+v, want [%+v]", preflight.Issues, want) + } +} + +func TestPreflight_UnknownRequirementIsNeverSatisfied(t *testing.T) { + // A token shaped like a provider is still only an unknown token: the + // vocabulary has no way to name a component, so a matcher with that name + // running earlier does not satisfy it. + for _, token := range []plugin.Requirement{"package-update-deltas-v9", "osv-matcher-v1"} { + t.Run(string(token), func(t *testing.T) { + registry, req := preflightScenario(t, preflightGraph(t)) + registry.registerMatcher(preflightMatcher{descriptor: plugin.MatcherDescriptor{Name: "osv-matcher"}, vulnerabilities: true, calls: &calls{}}) + auditor := &calls{} + registry.registerAuditor(preflightAuditor{descriptor: plugin.AuditorDescriptor{Name: "future", Requires: requires(token)}, calls: auditor}) + req.EnrichEnabled, req.AuditEnabled = true, true + + result, err := NewPipeline(registry, zap.NewNop()).Run(context.Background(), req) + if err != nil { + t.Fatalf("Run() error = %v", err) + } + if *auditor != (calls{}) { + t.Fatalf("an unknown requirement must hold the component back, got %+v", *auditor) + } + if len(result.AuditWarnings) == 0 || !strings.Contains(result.AuditWarnings[0].Message, "does not know this requirement") { + t.Fatalf("expected an unsupported-requirement diagnostic, got %v", result.AuditWarnings) + } + + req.AuditorFilter = plugin.AuditorFilter{Include: []string{"future"}} + _, err = NewPipeline(registry, zap.NewNop()).Run(context.Background(), req) + if _, ok := errors.AsType[*PreflightError](err); !ok { + t.Fatalf("an explicitly selected component with an unknown requirement must fail, got %v", err) + } + }) + } +} + +func TestPreflight_StageDataRequirementsSkipWhateverTheSelection(t *testing.T) { + // A requirement the plan could meet but this input did not -- no + // vulnerability was found, no dependency was detected -- skips the + // component even when the user named it: nothing in the command would + // make it run on this input. + cases := []struct { + name string + enrich bool + want string + }{ + {"no matcher ran", false, "no matcher ran; add --enrich"}, + {"matchers found nothing", true, "no package carries a vulnerability record"}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + registry, req := preflightScenario(t, preflightGraph(t)) + registry.registerMatcher(preflightMatcher{descriptor: plugin.MatcherDescriptor{Name: "license-matcher"}, calls: &calls{}}) + analyzer := &calls{} + registry.RegisterAnalyzer(preflightAnalyzer{descriptor: plugin.AnalyzerDescriptor{Name: "reach", Requires: requires(plugin.RequirementVulnerabilityRecords)}, applicable: true, calls: analyzer}) + req.EnrichEnabled, req.AnalyzeReachabilityEnabled = tc.enrich, true + req.AnalyzerFilter = plugin.AnalyzerFilter{Include: []string{"reach"}} + + result, err := NewPipeline(registry, zap.NewNop()).Run(context.Background(), req) + if err != nil { + t.Fatalf("a data-dependent requirement must not fail the plan, got %v", err) + } + if *analyzer != (calls{}) { + t.Fatalf("analyzer must be held back, got %+v", *analyzer) + } + if len(result.AnalyzeWarnings) != 1 || !strings.Contains(result.AnalyzeWarnings[0].Message, tc.want) { + t.Fatalf("expected %q, got %v", tc.want, result.AnalyzeWarnings) + } + }) + } +} + +func TestPreflight_DependencyGraphIsCheckedAgainstTheGraphTheStageReceives(t *testing.T) { + // Only the project's own module: a graph, but no dependency in it. + moduleOnly := model.New() + if err := moduleOnly.AddNode(testnodes.Module("package.json", "app", "1.0.0")); err != nil { + t.Fatalf("add module: %v", err) + } + registry, req := preflightScenario(t, moduleOnly) + auditor := &calls{} + registry.registerAuditor(preflightAuditor{descriptor: plugin.AuditorDescriptor{Name: "graph-auditor", Requires: requires(plugin.RequirementDependencyGraph)}, calls: auditor}) + req.AuditEnabled = true + + result, err := NewPipeline(registry, zap.NewNop()).Run(context.Background(), req) + if err != nil { + t.Fatalf("Run() error = %v", err) + } + if *auditor != (calls{}) { + t.Fatalf("an auditor requiring a dependency graph must not run on a graph with no dependency, got %+v", *auditor) + } + if len(result.AuditWarnings) == 0 || !strings.Contains(result.AuditWarnings[0].Message, "detection found no dependencies") { + t.Fatalf("expected a no-dependency diagnostic, got %v", result.AuditWarnings) + } +} + +func TestPreflight_DetectorsCannotRequireWhatLaterStagesProduce(t *testing.T) { + for _, token := range []plugin.Requirement{plugin.RequirementDependencyGraph, plugin.RequirementVulnerabilityRecords} { + t.Run(string(token), func(t *testing.T) { + graph := preflightGraph(t) + registry := newTestRegistry() + resolved := false + registry.registerDetector(fakeDetector{ + descriptor: DetectorDescriptor{Name: "needy", SupportedEcosystems: []Ecosystem{EcosystemNPM}, SupportedManagers: []PackageManager{PackageManagerNPM}, Requires: requires(token)}, + onResolve: func(ResolveGraphRequest) { resolved = true }, + }) + registry.registerDetector(fakeDetector{ + descriptor: DetectorDescriptor{Name: "npm-detector", SupportedEcosystems: []Ecosystem{EcosystemNPM}, SupportedManagers: []PackageManager{PackageManagerNPM}}, + result: ResolveGraphResult{Graphs: SingleGraphContainer(graph, model.ManifestMetadata{Path: "package-lock.json", Kind: "package-lock.json"})}, + }) + target := ExecutionTarget{Kind: ExecutionTargetFilesystem, Location: "/repo"} + req := PipelineRequest{ExecutionTarget: target, Subprojects: []Subproject{{ + ExecutionTarget: target, + RelativePath: ".", + PlannedDetectors: []string{"needy", "npm-detector"}, + DetectedPackageManagers: []PackageManager{PackageManagerNPM}, + Ecosystem: EcosystemNPM, + }}} + + result, err := NewPipeline(registry, zap.NewNop()).Run(context.Background(), req) + if err != nil { + t.Fatalf("a default detector must be skipped, not fail the run: %v", err) + } + if resolved { + t.Fatal("preflight must hold the detector back before it resolves") + } + if len(result.ResolveResults) != 1 || result.ResolveResults[0].DetectorName != "npm-detector" { + t.Fatalf("the next link of the chain must resolve the subproject, got %+v", result.ResolveResults) + } + var found bool + for _, warning := range result.DetectorWarnings { + if warning.Source == "needy" && warning.DegradesCoverage() && strings.Contains(warning.Message, "requires "+string(token)) { + found = true + } + } + if !found { + t.Fatalf("expected a coverage-degrading detector diagnostic, got %+v", result.DetectorWarnings) + } + + req.DetectorFilter = plugin.DetectorFilter{Include: []string{"needy", "npm-detector"}} + if _, err := NewPipeline(registry, zap.NewNop()).Run(context.Background(), req); err == nil { + t.Fatal("an explicitly selected detector with an impossible requirement must fail the run") + } + }) + } +} + +func TestPreflight_EmptyRegistryPlansNothing(t *testing.T) { + pipeline := NewPipeline(newTestRegistry(), zap.NewNop()) + req := PipelineRequest{EnrichEnabled: true, AnalyzeReachabilityEnabled: true, AuditEnabled: true} + if err := pipeline.preflightPlan(req); err != nil { + t.Fatalf("an empty registry has nothing to reject, got %v", err) + } + for _, stage := range plannedStages(req) { + stagePipeline, issues := pipeline.preflightStage(stage, req, nil, nil) + if stagePipeline != pipeline || len(issues) != 0 { + t.Fatalf("stage %s: nothing to hold back, got %v", stage, issues) + } + } +} + +func TestPreflight_HostVouchesOnlyForWhatEachStageHas(t *testing.T) { + sourceTree := targetShape{sourceTree: true} + cases := []struct { + facts preflightFacts + want []plugin.Requirement + }{ + {preflightFacts{stage: StageDetect, planning: true, target: sourceTree}, []plugin.Requirement{plugin.RequirementSourceTree}}, + {preflightFacts{stage: StageMatch, planning: true, target: sourceTree}, []plugin.Requirement{plugin.RequirementSourceTree, plugin.RequirementDependencyGraph}}, + {preflightFacts{stage: StageAnalyze, planning: true}, []plugin.Requirement{plugin.RequirementDependencyGraph, plugin.RequirementVulnerabilityRecords}}, + {preflightFacts{stage: StageAudit}, nil}, + {preflightFacts{stage: StageAudit, dependencyNodes: true, vulnerabilityRecords: true}, []plugin.Requirement{plugin.RequirementDependencyGraph, plugin.RequirementVulnerabilityRecords}}, + {preflightFacts{stage: StageMatch, dependencyNodes: true, vulnerabilityRecords: true}, []plugin.Requirement{plugin.RequirementDependencyGraph}}, + } + for _, tc := range cases { + got := tc.facts.available() + if len(got) != len(tc.want) { + t.Errorf("%+v: available = %v, want %v", tc.facts, got, tc.want) + continue + } + for i := range got { + if got[i] != tc.want[i] { + t.Errorf("%+v: available = %v, want %v", tc.facts, got, tc.want) + } + } + for _, requirement := range got { + if !requirement.Known() { + t.Errorf("the host must only vouch for SDK-known requirements, got %q", requirement) + } + } + } +} + +func TestPreflight_ExplicitSelectionFollowsTheSelectorGrammar(t *testing.T) { + includes := func(names ...string) func(string) bool { + return func(name string) bool { return plugin.MatcherFilter{Include: names}.Includes(name) } + } + cases := []struct { + name string + include []string + exclude []string + defaultEnabled bool + want bool + }{ + {"no selector: the default set", nil, nil, true, false}, + {"named in a plain list", []string{"osv"}, nil, true, true}, + {"another component named in a plain list", []string{"grype"}, nil, false, false}, + {"default-off component added with +name", nil, []string{"scorecard"}, false, true}, + {"default-on component repeated with +name", nil, []string{"scorecard"}, true, false}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + if got := selectedExplicitly(tc.include, tc.exclude, includes(tc.include...), "osv", tc.defaultEnabled); got != tc.want { + t.Fatalf("selectedExplicitly = %v, want %v", got, tc.want) + } + }) + } +} + +func TestPreflight_OperatorSelectedDefaultOffComponentIsExplicit(t *testing.T) { + graph := preflightGraph(t) + registry, req := preflightScenario(t, graph) + sbomTarget(registry, &req, graph) + registry.RegisterMatcherWithOptions(preflightMatcher{ + descriptor: plugin.MatcherDescriptor{Name: "opt-in", Requires: requires(plugin.RequirementSourceTree)}, + calls: &calls{}, + }, ComponentOptions{DefaultEnabled: false}) + registry.registerMatcher(preflightMatcher{descriptor: plugin.MatcherDescriptor{Name: "default-on"}, calls: &calls{}}) + req.EnrichEnabled = true + // What "--matchers +opt-in" resolves to when one other matcher is + // registered and left in: an exclude-only filter. + req.MatcherFilter = plugin.MatcherFilter{Exclude: []string{"unrelated"}} + + _, err := NewPipeline(registry, zap.NewNop()).Run(context.Background(), req) + preflight, ok := errors.AsType[*PreflightError](err) + if !ok || len(preflight.Issues) != 1 || preflight.Issues[0].Component != "opt-in" { + t.Fatalf("a default-off component added with +name is the user's explicit choice, got %v", err) + } +} diff --git a/internal/registry/view.go b/internal/registry/view.go new file mode 100644 index 00000000..ccc7badc --- /dev/null +++ b/internal/registry/view.go @@ -0,0 +1,49 @@ +package registry + +import ( + "slices" + + "github.com/bomly-dev/bomly-sdk/plugin" +) + +// DefaultEnabled reports whether the registry selects the named component of +// kind when the user's selector does not mention it. +func (r *Registry) DefaultEnabled(kind plugin.PluginKind, name string) bool { + return r.isDefaultEnabled(kind, name) +} + +// Without returns a view of the registry that leaves out the named +// components of one kind and shares every other registration. Runtime +// preflight uses it to hold a component back from a stage without touching +// the selection filters the component itself is sent. +// +// The view owns no component lifetime: closing it ends nothing, because the +// registry it came from still owns every component it constructed. +func (r *Registry) Without(kind plugin.PluginKind, names []string) *Registry { + if r == nil || len(names) == 0 { + return r + } + view := *r + view.scopes = nil + switch kind { + case plugin.PluginKindDetector: + view.detectors = withoutNamed(r.detectors, names, func(d plugin.Detector) string { return d.Descriptor().Name }) + case plugin.PluginKindMatcher: + view.matchers = withoutNamed(r.matchers, names, func(m plugin.Matcher) string { return m.Descriptor().Name }) + case plugin.PluginKindAnalyzer: + view.analyzers = withoutNamed(r.analyzers, names, func(a plugin.Analyzer) string { return a.Descriptor().Name }) + case plugin.PluginKindAuditor: + view.auditors = withoutNamed(r.auditors, names, func(a plugin.Auditor) string { return a.Descriptor().Name }) + } + return &view +} + +func withoutNamed[T any](items []T, names []string, name func(T) string) []T { + kept := make([]T, 0, len(items)) + for _, item := range items { + if !slices.Contains(names, name(item)) { + kept = append(kept, item) + } + } + return kept +} diff --git a/internal/registry/view_test.go b/internal/registry/view_test.go new file mode 100644 index 00000000..26d4a0f2 --- /dev/null +++ b/internal/registry/view_test.go @@ -0,0 +1,56 @@ +package registry + +import ( + "context" + "testing" + + "go.uber.org/zap" + + "github.com/bomly-dev/bomly-sdk/plugin" +) + +func TestWithoutLeavesOutOnlyTheNamedComponentsOfOneKind(t *testing.T) { + registry := NewRegistry(Configs{}, *zap.NewNop()) + registry.RegisterMatcher(&moduleTestMatcher{name: "kept"}) + registry.RegisterMatcher(&moduleTestMatcher{name: "held-back"}) + registry.RegisterMatcherWithOptions(&moduleTestMatcher{name: "opt-in"}, ComponentOptions{DefaultEnabled: false}) + + view := registry.Without(plugin.PluginKindMatcher, []string{"held-back"}) + var names []string + for _, matcher := range view.Matchers(plugin.MatchRequest{}) { + names = append(names, matcher.Descriptor().Name) + } + if len(names) != 1 || names[0] != "kept" { + t.Fatalf("view matchers = %v, want [kept]", names) + } + if got := len(registry.Matchers(plugin.MatchRequest{})); got != 2 { + t.Fatalf("the view must not change the registry it came from, which now selects %d matchers", got) + } + if !view.DefaultEnabled(plugin.PluginKindMatcher, "kept") || view.DefaultEnabled(plugin.PluginKindMatcher, "opt-in") { + t.Fatal("the view must keep the registry's default selection") + } + if same := registry.Without(plugin.PluginKindMatcher, nil); same != registry { + t.Fatal("holding nothing back must return the registry itself") + } +} + +func TestWithoutViewOwnsNoComponentLifetime(t *testing.T) { + registry := NewRegistry(Configs{}, *zap.NewNop()) + ended := 0 + err := registry.RegisterModule(plugin.Module{Kind: plugin.PluginKindMatcher, Matcher: &plugin.MatcherModule{ + Descriptor: plugin.MatcherDescriptor{Name: "scoped"}, + New: func(_ context.Context, host plugin.HostContext) (plugin.Matcher, error) { + host.OnCleanup(func() error { ended++; return nil }) + return &moduleTestMatcher{name: "scoped"}, nil + }, + }}, ComponentOptions{DefaultEnabled: true}) + if err != nil { + t.Fatalf("RegisterModule: %v", err) + } + if err := registry.Without(plugin.PluginKindMatcher, []string{"scoped"}).Close(); err != nil || ended != 0 { + t.Fatalf("closing a view must end nothing: err=%v ended=%d", err, ended) + } + if err := registry.Close(); err != nil || ended != 1 { + t.Fatalf("the registry still owns the component: err=%v ended=%d", err, ended) + } +} From 5c339d953120ca84130ac8d47887980f02402737 Mon Sep 17 00:00:00 2001 From: Ahmed ElMallah Date: Sun, 25 Oct 2026 01:04:48 -0700 Subject: [PATCH 03/10] feat(plugins): disclose declared access and requirements in plugin views A package manifest may now carry the SDK's access block (bomly-sdk v0.16.0 plugin.Access), validated only through plugin.ValidateAccess. A malformed block fails the install; an absent one keeps installing and reads as unknown, never as "no access". Install, enable (before the plugin is enabled), info, verify and doctor show it as the publisher's unverified claim through one renderer, and the JSON views carry it with accessDisclosure set to declared or unknown. Nothing is enforced. Declared requirements appear in `plugins info` (unknown tokens marked) and in generated matcher, auditor and detector-chain pages when a component declares any; no built-in does yet, so the generated docs are unchanged. The installed-snapshot comparison now includes requirements, so a binary whose declared requirements changed since install fails verify, and the descriptor clone helpers delegate to the SDK's Clone, which copies them. Refs bomly-dev/bomly-cli#417 Refs bomly-dev/bomly-cli#418 Co-Authored-By: Claude Opus 5.5 --- internal/cli/plugin_access.go | 110 +++++++++++++++++ internal/cli/plugin_access_test.go | 187 +++++++++++++++++++++++++++++ internal/cli/plugin_cmd.go | 51 +++++--- internal/plugin/access_test.go | 139 +++++++++++++++++++++ internal/plugin/test.go | 7 +- internal/plugin/types.go | 70 ++++++----- internal/plugin/verify.go | 15 +++ internal/support/component_docs.go | 35 ++++++ internal/support/docs_gen_test.go | 16 +++ 9 files changed, 580 insertions(+), 50 deletions(-) create mode 100644 internal/cli/plugin_access.go create mode 100644 internal/cli/plugin_access_test.go create mode 100644 internal/plugin/access_test.go diff --git a/internal/cli/plugin_access.go b/internal/cli/plugin_access.go new file mode 100644 index 00000000..2cf1729e --- /dev/null +++ b/internal/cli/plugin_access.go @@ -0,0 +1,110 @@ +package cli + +import ( + "fmt" + "io" + "strings" + + "github.com/bomly-dev/bomly-cli/internal/engine" + managedplugin "github.com/bomly-dev/bomly-cli/internal/plugin" + + "github.com/bomly-dev/bomly-sdk/plugin" +) + +// renderAccessDisclosure writes a managed plugin's declared access, labelled +// as the publisher's unverified claim. Bomly enforces none of it: a managed +// plugin is a native process with the invoking user's authority, so the +// wording never says the plugin is limited to what it declares. A manifest +// with no access block is shown as unknown, which means unrestricted. +// +// Every install, enable, info, verify and doctor view goes through this one +// function, so the label cannot drift between them. +func renderAccessDisclosure(w io.Writer, access *plugin.Access) error { + if access == nil { + _, err := fmt.Fprint(w, "Declared access: unknown\n"+ + " The manifest declares no access. Assume the plugin can use everything your\n"+ + " user account can: files, network, environment variables, and child processes.\n") + return err + } + rows := [][2]string{ + {"Filesystem read", accessList(scopeStrings(access.FilesystemRead), "")}, + {"Filesystem write", accessList(scopeStrings(access.FilesystemWrite), "")}, + {"Network", accessList(access.Network, "any destination")}, + {"Environment", accessList(access.Environment, "any variable")}, + {"Subprocesses", accessList(access.Subprocesses, "any command")}, + } + if _, err := fmt.Fprint(w, "Declared access (the publisher's claim; Bomly does not verify or enforce it):\n"); err != nil { + return err + } + for _, row := range rows { + if _, err := fmt.Fprintf(w, " %-16s : %s\n", row[0], row[1]); err != nil { + return err + } + } + return nil +} + +// accessList joins one declared list for display. An empty list is the +// publisher's claim of no access of that kind. anyLabel names the +// plugin.AccessAny entry in words, when the list allows one. +func accessList(values []string, anyLabel string) string { + if len(values) == 0 { + return "none declared" + } + out := make([]string, 0, len(values)) + for _, value := range values { + if value == plugin.AccessAny && anyLabel != "" { + value = anyLabel + } + out = append(out, value) + } + return strings.Join(out, ", ") +} + +func scopeStrings(scopes []plugin.FilesystemScope) []string { + out := make([]string, len(scopes)) + for i, scope := range scopes { + out[i] = string(scope) + } + return out +} + +// renderInstalledAccess writes the disclosure for an installed managed +// plugin and nothing for a built-in component, which is part of Bomly. +func renderInstalledAccess(w io.Writer, info managedplugin.Info) error { + if info.BuiltIn { + return nil + } + return renderAccessDisclosure(w, info.Access) +} + +// pluginInfoRequirements returns the requirements a component's descriptor +// declares, whichever kind it is. +func pluginInfoRequirements(info managedplugin.Info) plugin.Requirements { + switch { + case info.DetectorDescriptor != nil: + return info.DetectorDescriptor.Requires.Normalized() + case info.MatcherDescriptor != nil: + return info.MatcherDescriptor.Requires.Normalized() + case info.AuditorDescriptor != nil: + return info.AuditorDescriptor.Requires.Normalized() + case info.AnalyzerDescriptor != nil: + return info.AnalyzerDescriptor.Requires.Normalized() + default: + return nil + } +} + +// joinRequirements renders declared requirements, marking any token this +// Bomly cannot evaluate, since preflight treats it as never satisfied. +func joinRequirements(requirements plugin.Requirements) string { + out := make([]string, 0, len(requirements)) + for _, requirement := range requirements { + value := string(requirement) + if !engine.Evaluates(requirement) { + value += " (unknown to this Bomly version)" + } + out = append(out, value) + } + return strings.Join(out, ", ") +} diff --git a/internal/cli/plugin_access_test.go b/internal/cli/plugin_access_test.go new file mode 100644 index 00000000..d3f2d596 --- /dev/null +++ b/internal/cli/plugin_access_test.go @@ -0,0 +1,187 @@ +package cli + +import ( + "context" + "encoding/json" + "os" + "path/filepath" + "strings" + "testing" + + managedplugin "github.com/bomly-dev/bomly-cli/internal/plugin" + testutil "github.com/bomly-dev/bomly-sdk/testkit" + + "github.com/bomly-dev/bomly-sdk/plugin" +) + +// enforcementClaims are phrasings that would present a publisher's +// declaration as a restriction Bomly applies. +var enforcementClaims = []string{"is limited to", "is restricted to", "sandbox", "only has access", "enforced by"} + +func TestRenderAccessDisclosureLabelsTheClaimAsUnverified(t *testing.T) { + var declared strings.Builder + if err := renderAccessDisclosure(&declared, &plugin.Access{ + FilesystemRead: []plugin.FilesystemScope{plugin.FilesystemCache, plugin.FilesystemProject}, + Network: []string{plugin.AccessAny, "api.osv.dev"}, + Environment: []string{"GITHUB_TOKEN"}, + }); err != nil { + t.Fatalf("renderAccessDisclosure() error = %v", err) + } + for _, want := range []string{ + "the publisher's claim; Bomly does not verify or enforce it", + "Filesystem read : cache, project", + "Filesystem write : none declared", + "Network : any destination, api.osv.dev", + "Environment : GITHUB_TOKEN", + "Subprocesses : none declared", + } { + if !strings.Contains(declared.String(), want) { + t.Errorf("declared disclosure is missing %q:\n%s", want, declared.String()) + } + } + + var unknown strings.Builder + if err := renderAccessDisclosure(&unknown, nil); err != nil { + t.Fatalf("renderAccessDisclosure(nil) error = %v", err) + } + if !strings.Contains(unknown.String(), "Declared access: unknown") || !strings.Contains(unknown.String(), "can use everything your") { + t.Fatalf("a manifest without an access block must read as unknown and unrestricted, got:\n%s", unknown.String()) + } + for _, output := range []string{declared.String(), unknown.String()} { + for _, claim := range enforcementClaims { + if strings.Contains(strings.ToLower(output), claim) { + t.Errorf("disclosure must never claim enforcement (%q):\n%s", claim, output) + } + } + } +} + +func TestRenderPluginInfoShowsDeclaredRequirements(t *testing.T) { + info := managedplugin.Info{ + Manifest: managedplugin.Manifest{ID: "reach", Name: "reach", Kind: plugin.PluginKindAnalyzer, Version: "1.0.0", Runtime: "builtin"}, + AnalyzerDescriptor: &plugin.AnalyzerDescriptor{ + Name: "reach", + Requires: plugin.Requirements{plugin.RequirementVulnerabilityRecords, "future-input-v2", plugin.RequirementSourceTree}, + }, + BuiltIn: true, + } + var output strings.Builder + if err := renderPluginInfo(&output, info); err != nil { + t.Fatalf("renderPluginInfo() error = %v", err) + } + want := "Requires : future-input-v2 (unknown to this Bomly version), source-tree-v1, vulnerability-records-v1" + if !strings.Contains(output.String(), want) { + t.Fatalf("renderPluginInfo() must list the declared requirements, sorted, got:\n%s", output.String()) + } + if strings.Contains(output.String(), "Declared access") { + t.Fatalf("a built-in component is part of Bomly and carries no publisher disclosure:\n%s", output.String()) + } +} + +func TestPluginEnableShowsTheDisclosureBeforeEnabling(t *testing.T) { + root := newPluginTestRoot(t) + id := "acme.detector.cli.access" + declareInstalledAccess(t, installCLIAccessDetectorPlugin(t, id), `{"network":["API.Example.com"],"subprocesses":["go"]}`) + + var output strings.Builder + root.SetOut(&output) + root.SetErr(&output) + root.SetArgs([]string{"plugin", "enable", id}) + if err := root.Execute(); err != nil { + t.Fatalf("plugin enable error = %v", err) + } + text := output.String() + assertInOrder(t, text, []string{"Declared access (the publisher's claim", "Network : api.example.com", "enabled " + id}) +} + +func TestPluginJSONViewsExposeTheDisclosureState(t *testing.T) { + root := newPluginTestRoot(t) + legacy := "acme.detector.cli.legacy" + declared := "acme.detector.cli.declared" + installCLIAccessDetectorPlugin(t, legacy) + declareInstalledAccess(t, installCLIAccessDetectorPlugin(t, declared), `{}`) + + var list strings.Builder + root.SetOut(&list) + root.SetArgs([]string{"plugin", "list", "--external", "--json"}) + if err := root.Execute(); err != nil { + t.Fatalf("plugin list error = %v", err) + } + var response managedplugin.ListResponse + if err := json.Unmarshal([]byte(list.String()), &response); err != nil { + t.Fatalf("decode plugin list: %v\n%s", err, list.String()) + } + states := map[string]managedplugin.AccessDisclosure{} + for _, info := range response.Detectors { + states[info.ID] = info.AccessDisclosure + if info.ID == declared && (info.Access == nil || info.Access.Network != nil) { + t.Fatalf("an empty access block is a claim of no access and must survive as one, got %+v", info.Access) + } + } + if states[legacy] != managedplugin.AccessUnknown || states[declared] != managedplugin.AccessDeclared { + t.Fatalf("plugin list --json disclosure states = %v", states) + } + + for _, command := range []string{"verify", "doctor"} { + var output strings.Builder + // A fresh root over the same plugin store: newPluginTestRoot would + // point HOME somewhere empty. + root, err := newRootCmd("0.9.0-test") + if err != nil { + t.Fatalf("newRootCmd() error = %v", err) + } + root.SetOut(&output) + root.SetArgs([]string{"plugin", command, declared, "--json"}) + if err := root.Execute(); err != nil { + t.Fatalf("plugin %s error = %v", command, err) + } + var result map[string]any + if err := json.Unmarshal([]byte(output.String()), &result); err != nil { + t.Fatalf("decode plugin %s: %v\n%s", command, err, output.String()) + } + if result["accessDisclosure"] != string(managedplugin.AccessDeclared) || result["access"] == nil { + t.Fatalf("plugin %s --json must carry the declared access, got %v", command, result) + } + } +} + +// installCLIAccessDetectorPlugin dev-installs a fake detector into a plugin +// store private to the test, so no other test sees it. +func installCLIAccessDetectorPlugin(t *testing.T, id string) string { + t.Helper() + if os.Getenv(managedplugin.EnvPluginHome) == "" { + t.Setenv(managedplugin.EnvPluginHome, t.TempDir()) + } + binaryPath := filepath.Join(t.TempDir(), cliTestExecutableName("bomly-plugin-cli-access")) + if err := testutil.BuildGoBinary(t, binaryPath, cliHealthDetectorPluginSource(id, true)); err != nil { + t.Fatalf("build fake plugin: %v", err) + } + result, err := managedplugin.Install(context.Background(), "", binaryPath, managedplugin.InstallOptions{DevBinary: true}) + if err != nil { + t.Fatalf("Install() error = %v", err) + } + return result.Installed.Path +} + +// declareInstalledAccess adds an access block to an installed plugin's +// manifest, as a published package would carry it. +func declareInstalledAccess(t *testing.T, dir, access string) { + t.Helper() + path := filepath.Join(dir, "bomly-plugin.json") + data, err := os.ReadFile(path) + if err != nil { + t.Fatalf("read manifest: %v", err) + } + var manifest map[string]json.RawMessage + if err := json.Unmarshal(data, &manifest); err != nil { + t.Fatalf("decode manifest: %v", err) + } + manifest["access"] = json.RawMessage(access) + data, err = json.Marshal(manifest) + if err != nil { + t.Fatalf("encode manifest: %v", err) + } + if err := os.WriteFile(path, data, 0o644); err != nil { + t.Fatalf("write manifest: %v", err) + } +} diff --git a/internal/cli/plugin_cmd.go b/internal/cli/plugin_cmd.go index ac32778a..a520bf3f 100644 --- a/internal/cli/plugin_cmd.go +++ b/internal/cli/plugin_cmd.go @@ -245,6 +245,11 @@ func newPluginInstallCmd() *cobra.Command { if err != nil { return err } + // Installed plugins start disabled: show what the publisher + // declares before the user decides to enable it. + if err := renderAccessDisclosure(streams.reportWriter(), result.Manifest.Access); err != nil { + return err + } if devBinary { _, _ = fmt.Fprintf(cmd.ErrOrStderr(), "Warning: installed in development mode — no checksum was recorded. Only enable plugins you built or fully trust.\n") @@ -293,12 +298,22 @@ func newPluginEnableCmd() *cobra.Command { if err != nil { return err } - pluginRecord, err := managedplugin.Enable("", strings.TrimSpace(args[0])) + id := strings.TrimSpace(args[0]) + // The disclosure is read and shown before the plugin is + // enabled, because enabling it is the trust decision. + manifest, err := managedplugin.InstalledManifest("", id) if err != nil { return err } current := options.GetConfig() streams := newCommandStreams(cmd, current.Quiet, current.Verbosity) + if err := renderAccessDisclosure(streams.reportWriter(), manifest.Access); err != nil { + return err + } + pluginRecord, err := managedplugin.Enable("", id) + if err != nil { + return err + } if _, err := fmt.Fprintf(streams.reportWriter(), "enabled %s@%s\n", pluginRecord.ID, pluginRecord.Version); err != nil { return err } @@ -374,7 +389,9 @@ func newPluginVerifyCmd() *cobra.Command { return err } } - return nil + // Verification covers integrity and identity, not behavior: + // the declared access is shown beside it, never as a check. + return renderAccessDisclosure(streams.reportWriter(), result.Access) }, } cmd.Flags().BoolVar(&jsonOutput, "json", false, "Render verification results as JSON") @@ -469,6 +486,9 @@ func newPluginDoctorCmd() *cobra.Command { if _, err := fmt.Fprintf(streams.reportWriter(), "%s %s: %s\n", label, nonEmptyString(result.Probe, "runtime readiness"), status); err != nil { return err } + if err := renderInstalledAccess(streams.reportWriter(), result.Info); err != nil { + return err + } } if !result.Healthy { return fmt.Errorf("plugin %s is unhealthy", result.ID) @@ -772,13 +792,7 @@ func cloneMatcherDescriptor(descriptor *plugin.MatcherDescriptor) *plugin.Matche if descriptor == nil { return nil } - copyValue := *descriptor - copyValue.SupportedEcosystems = append([]model.Ecosystem(nil), descriptor.SupportedEcosystems...) - copyValue.SupportedManagers = append([]model.PackageManager(nil), descriptor.SupportedManagers...) - copyValue.Aliases = append([]string(nil), descriptor.Aliases...) - copyValue.Tags = append([]string(nil), descriptor.Tags...) - copyValue.Capabilities = append([]string(nil), descriptor.Capabilities...) - copyValue.ConfigSchema = append(json.RawMessage(nil), descriptor.ConfigSchema...) + copyValue := descriptor.Clone() return ©Value } @@ -786,10 +800,7 @@ func cloneAuditorDescriptor(descriptor *plugin.AuditorDescriptor) *plugin.Audito if descriptor == nil { return nil } - copyValue := *descriptor - copyValue.SupportedEcosystems = append([]model.Ecosystem(nil), descriptor.SupportedEcosystems...) - copyValue.SupportedManagers = append([]model.PackageManager(nil), descriptor.SupportedManagers...) - copyValue.ConfigSchema = append(json.RawMessage(nil), descriptor.ConfigSchema...) + copyValue := descriptor.Clone() return ©Value } @@ -797,13 +808,7 @@ func cloneAnalyzerDescriptor(descriptor *plugin.AnalyzerDescriptor) *plugin.Anal if descriptor == nil { return nil } - copyValue := *descriptor - copyValue.SupportedEcosystems = append([]model.Ecosystem(nil), descriptor.SupportedEcosystems...) - copyValue.SupportedManagers = append([]model.PackageManager(nil), descriptor.SupportedManagers...) - copyValue.SupportedLanguages = append([]model.Language(nil), descriptor.SupportedLanguages...) - copyValue.SupportedTiers = append([]model.ReachabilityTier(nil), descriptor.SupportedTiers...) - copyValue.Capabilities = append([]string(nil), descriptor.Capabilities...) - copyValue.ConfigSchema = append(json.RawMessage(nil), descriptor.ConfigSchema...) + copyValue := descriptor.Clone() return ©Value } @@ -847,6 +852,9 @@ func renderPluginInfo(w io.Writer, info managedplugin.Info) error { if tags := pluginInfoTags(info); len(tags) > 0 { lines = append(lines, [2]string{"Tags", strings.Join(tags, ", ")}) } + if requirements := pluginInfoRequirements(info); len(requirements) > 0 { + lines = append(lines, [2]string{"Requires", joinRequirements(requirements)}) + } if info.Description != "" { lines = append(lines, [2]string{"Description", info.Description}) } @@ -870,6 +878,9 @@ func renderPluginInfo(w io.Writer, info managedplugin.Info) error { return err } } + if err := renderInstalledAccess(w, info); err != nil { + return err + } return renderPluginConfigSchema(w, pluginInfoConfigSchema(info)) } diff --git a/internal/plugin/access_test.go b/internal/plugin/access_test.go new file mode 100644 index 00000000..0f251c5a --- /dev/null +++ b/internal/plugin/access_test.go @@ -0,0 +1,139 @@ +package plugin + +import ( + "context" + "os" + "path/filepath" + "runtime" + "slices" + "strings" + "testing" + + testutil "github.com/bomly-dev/bomly-sdk/testkit" + + sdkplugin "github.com/bomly-dev/bomly-sdk/plugin" +) + +func accessTestManifest(access *sdkplugin.Access) Manifest { + return withCanonicalManifestDefaults(Manifest{ + ID: "acme.matcher.access", + Name: "acme access matcher", + Version: "1.0.0", + Kind: sdkplugin.PluginKindMatcher, + Entrypoint: map[string]string{platformKey(): "bin/matcher"}, + Access: access, + }, "test") +} + +func TestValidateManifestDelegatesAccessToTheSDKGate(t *testing.T) { + if err := validateManifest(accessTestManifest(nil)); err != nil { + t.Fatalf("a legacy manifest without an access block must stay valid: %v", err) + } + if err := validateManifest(accessTestManifest(&sdkplugin.Access{})); err != nil { + t.Fatalf("an empty block, a claim of no access, must be valid: %v", err) + } + valid := &sdkplugin.Access{Network: []string{"*.github.com", "api.osv.dev"}, Environment: []string{"BOMLY_HTTP_*"}, Subprocesses: []string{"go"}} + if err := validateManifest(accessTestManifest(valid)); err != nil { + t.Fatalf("validateManifest() rejected a well-formed disclosure: %v", err) + } + for name, access := range map[string]*sdkplugin.Access{ + "host with a path": {Network: []string{"example.com/path"}}, + "environment value": {Environment: []string{"TOKEN=secret"}}, + "command with a path": {Subprocesses: []string{"/usr/bin/go"}}, + "too many entries": {Subprocesses: slices.Repeat([]string{"go"}, sdkplugin.MaxAccessEntries+1)}, + "malformed scope name": {FilesystemRead: []sdkplugin.FilesystemScope{"Project Dir"}}, + } { + err := validateManifest(accessTestManifest(access)) + if err == nil || !strings.Contains(err.Error(), "plugin manifest access") { + t.Errorf("%s: validateManifest() = %v, want the SDK's access error", name, err) + } + } +} + +func TestManifestAccessDisclosureNeverReadsAbsenceAsNoAccess(t *testing.T) { + if got := accessTestManifest(nil).AccessDisclosure(); got != AccessUnknown { + t.Fatalf("absent access block = %q, want %q", got, AccessUnknown) + } + if got := accessTestManifest(&sdkplugin.Access{}).AccessDisclosure(); got != AccessDeclared { + t.Fatalf("empty access block = %q, want %q", got, AccessDeclared) + } +} + +func TestInstallKeepsTheDeclaredAccessAndRefusesAMalformedOne(t *testing.T) { + binaryName := "bomly-plugin-access" + if runtime.GOOS == "windows" { + binaryName += ".exe" + } + binaryPath := filepath.Join(t.TempDir(), binaryName) + if err := testutil.BuildGoBinary(t, binaryPath, fakeDetectorPluginSource("acme.detector.access")); err != nil { + t.Fatalf("build fake plugin: %v", err) + } + install := func(t *testing.T, root string, access *sdkplugin.Access) (*InstallResult, error) { + t.Helper() + manifest := withCanonicalManifestDefaults(Manifest{ + ID: "acme.detector.access", + Name: "Acme Access Detector", + Version: "1.0.0", + Kind: sdkplugin.PluginKindDetector, + Entrypoint: map[string]string{platformKey(): filepath.ToSlash(filepath.Join("bin", binaryName))}, + Access: access, + }, "local") + archive := filepath.Join(t.TempDir(), "plugin"+archiveSuffix()) + if err := os.WriteFile(archive, buildPluginArchive(t, manifest, binaryPath), 0o644); err != nil { + t.Fatalf("write archive: %v", err) + } + return Install(context.Background(), root, archive, InstallOptions{}) + } + + t.Run("declared", func(t *testing.T) { + root := t.TempDir() + if _, err := install(t, root, &sdkplugin.Access{Network: []string{"API.Example.COM", "api.example.com"}, Subprocesses: []string{"go"}}); err != nil { + t.Fatalf("Install() error = %v", err) + } + installed, err := LoadInstalledPlugins(root) + if err != nil || len(installed) != 1 { + t.Fatalf("LoadInstalledPlugins() = %v, %v", installed, err) + } + info := installed[0] + if info.AccessDisclosure != AccessDeclared || info.Access == nil || !slices.Equal(info.Access.Network, []string{"api.example.com"}) { + t.Fatalf("the installed disclosure must be the SDK-normalized declaration, got %q %+v", info.AccessDisclosure, info.Access) + } + }) + t.Run("legacy", func(t *testing.T) { + root := t.TempDir() + if _, err := install(t, root, nil); err != nil { + t.Fatalf("a manifest without an access block must keep installing: %v", err) + } + installed, err := LoadInstalledPlugins(root) + if err != nil || len(installed) != 1 || installed[0].AccessDisclosure != AccessUnknown || installed[0].Access != nil { + t.Fatalf("legacy install must read as unknown, got %+v, %v", installed, err) + } + }) + t.Run("malformed", func(t *testing.T) { + root := t.TempDir() + _, err := install(t, root, &sdkplugin.Access{Network: []string{"not a host"}}) + if err == nil || !strings.Contains(err.Error(), "access network entry") { + t.Fatalf("a malformed declaration must fail the install, not be dropped: %v", err) + } + if installed, _ := LoadInstalledPlugins(root); len(installed) != 0 { + t.Fatalf("a refused install must leave nothing installed, got %+v", installed) + } + }) +} + +func TestRuntimeSnapshotComparisonIncludesRequirements(t *testing.T) { + left := &sdkplugin.MatcherDescriptor{Name: "m", Requires: sdkplugin.Requirements{sdkplugin.RequirementDependencyGraph}} + same := &sdkplugin.MatcherDescriptor{Name: "m", Requires: sdkplugin.Requirements{sdkplugin.RequirementDependencyGraph, sdkplugin.RequirementDependencyGraph}} + changed := &sdkplugin.MatcherDescriptor{Name: "m", Requires: sdkplugin.Requirements{sdkplugin.RequirementSourceTree}} + if !matcherDescriptorEqual(left, same) { + t.Fatal("requirements equal after normalization must compare equal") + } + if matcherDescriptorEqual(left, changed) { + t.Fatal("a binary whose declared requirements changed since install must not match its snapshot") + } + clone := cloneMatcherDescriptor(left) + clone.Requires[0] = sdkplugin.RequirementSourceTree + if left.Requires[0] != sdkplugin.RequirementDependencyGraph { + t.Fatal("a cloned descriptor must not share its requirements with the original") + } +} diff --git a/internal/plugin/test.go b/internal/plugin/test.go index 1dd5d64d..6cbef7f8 100644 --- a/internal/plugin/test.go +++ b/internal/plugin/test.go @@ -80,9 +80,10 @@ func Test(ctx context.Context, root, id string, builtins []Info) (*TestResult, e return &TestResult{ Info: Info{ - Manifest: manifest, - Installed: record, - Entrypoint: fullEntrypoint, + Manifest: manifest, + Installed: record, + Entrypoint: fullEntrypoint, + AccessDisclosure: manifest.AccessDisclosure(), }, Ready: ready, Probe: probe, diff --git a/internal/plugin/types.go b/internal/plugin/types.go index 8a84b33b..be6e62ed 100644 --- a/internal/plugin/types.go +++ b/internal/plugin/types.go @@ -94,6 +94,33 @@ type Manifest struct { Description string `json:"description,omitempty"` Homepage string `json:"homepage,omitempty"` License string `json:"license,omitempty"` + // Access is the publisher's disclosure of the host access the plugin + // expects. It is an unverified claim, shown to the user before they + // enable the plugin and never enforced. Nil means the manifest discloses + // nothing, which is unknown and unrestricted, never "needs no access". + // Gate: sdkplugin.ValidateAccess, in validateManifest. + Access *sdkplugin.Access `json:"access,omitempty"` +} + +// AccessDisclosure says whether a managed plugin's manifest declares the +// access it expects. +type AccessDisclosure string + +const ( + // AccessDeclared means the manifest carries an access block: the + // publisher's claim, which Bomly shows but does not verify or enforce. + AccessDeclared AccessDisclosure = "declared" + // AccessUnknown means the manifest carries no access block, so the + // plugin may use anything the invoking user can. + AccessUnknown AccessDisclosure = "unknown" +) + +// AccessDisclosure reports whether the manifest declares its access. +func (m Manifest) AccessDisclosure() AccessDisclosure { + if m.Access == nil { + return AccessUnknown + } + return AccessDeclared } // RuntimeDescriptorSnapshot stores Bomly-verified runtime descriptors for an installed plugin. @@ -155,6 +182,9 @@ type Info struct { Enabled bool Entrypoint string SourceType string + // AccessDisclosure is set for an installed managed plugin, from its + // manifest; a built-in component is part of Bomly and has none. + AccessDisclosure AccessDisclosure `json:"accessDisclosure,omitempty"` // ReadyFn, when non-nil, is called by Test() to probe readiness for built-in plugins. // Populated by the CLI layer from the in-process component instance. // Never serialized to JSON. @@ -486,6 +516,9 @@ func validateManifest(manifest Manifest) error { if _, err := pathInPluginDir(".", entry); err != nil { return fmt.Errorf("plugin entrypoint %q must stay within the plugin directory", entry) } + if err := sdkplugin.ValidateAccess(manifest.Access); err != nil { + return fmt.Errorf("plugin manifest %w", err) + } return nil } @@ -766,6 +799,7 @@ func LoadInstalledPlugins(root string) ([]Info, error) { MatcherDescriptor: cloneMatcherDescriptor(snapshot.MatcherDescriptor), AuditorDescriptor: cloneAuditorDescriptor(snapshot.AuditorDescriptor), AnalyzerDescriptor: cloneAnalyzerDescriptor(snapshot.AnalyzerDescriptor), + AccessDisclosure: manifest.AccessDisclosure(), Installed: new(item), Enabled: item.Enabled, Entrypoint: fullEntrypoint, @@ -902,23 +936,24 @@ func componentDescriptorEqual(left, right sdkplugin.ComponentDescriptor) bool { slices.Equal(left.Aliases, right.Aliases) && slices.Equal(left.Tags, right.Tags) && slices.Equal(left.SupportedEcosystems, right.SupportedEcosystems) && - slices.Equal(left.SupportedManagers, right.SupportedManagers) + slices.Equal(left.SupportedManagers, right.SupportedManagers) && + slices.Equal(left.Requires.Normalized(), right.Requires.Normalized()) } func componentFromDetectorDescriptor(descriptor sdkplugin.DetectorDescriptor) sdkplugin.ComponentDescriptor { - return sdkplugin.ComponentDescriptor{Name: descriptor.Name, DisplayName: descriptor.DisplayName, Aliases: descriptor.Aliases, Tags: descriptor.Tags, SupportedEcosystems: descriptor.SupportedEcosystems, SupportedManagers: descriptor.SupportedManagers} + return sdkplugin.ComponentDescriptor{Name: descriptor.Name, DisplayName: descriptor.DisplayName, Aliases: descriptor.Aliases, Tags: descriptor.Tags, SupportedEcosystems: descriptor.SupportedEcosystems, SupportedManagers: descriptor.SupportedManagers, Requires: descriptor.Requires} } func componentFromMatcherDescriptor(descriptor sdkplugin.MatcherDescriptor) sdkplugin.ComponentDescriptor { - return sdkplugin.ComponentDescriptor{Name: descriptor.Name, DisplayName: descriptor.DisplayName, Aliases: descriptor.Aliases, Tags: descriptor.Tags, SupportedEcosystems: descriptor.SupportedEcosystems, SupportedManagers: descriptor.SupportedManagers} + return sdkplugin.ComponentDescriptor{Name: descriptor.Name, DisplayName: descriptor.DisplayName, Aliases: descriptor.Aliases, Tags: descriptor.Tags, SupportedEcosystems: descriptor.SupportedEcosystems, SupportedManagers: descriptor.SupportedManagers, Requires: descriptor.Requires} } func componentFromAuditorDescriptor(descriptor sdkplugin.AuditorDescriptor) sdkplugin.ComponentDescriptor { - return sdkplugin.ComponentDescriptor{Name: descriptor.Name, DisplayName: descriptor.DisplayName, Aliases: descriptor.Aliases, Tags: descriptor.Tags, SupportedEcosystems: descriptor.SupportedEcosystems, SupportedManagers: descriptor.SupportedManagers} + return sdkplugin.ComponentDescriptor{Name: descriptor.Name, DisplayName: descriptor.DisplayName, Aliases: descriptor.Aliases, Tags: descriptor.Tags, SupportedEcosystems: descriptor.SupportedEcosystems, SupportedManagers: descriptor.SupportedManagers, Requires: descriptor.Requires} } func componentFromAnalyzerDescriptor(descriptor sdkplugin.AnalyzerDescriptor) sdkplugin.ComponentDescriptor { - return sdkplugin.ComponentDescriptor{Name: descriptor.Name, DisplayName: descriptor.DisplayName, Aliases: descriptor.Aliases, Tags: descriptor.Tags, SupportedEcosystems: descriptor.SupportedEcosystems, SupportedManagers: descriptor.SupportedManagers} + return sdkplugin.ComponentDescriptor{Name: descriptor.Name, DisplayName: descriptor.DisplayName, Aliases: descriptor.Aliases, Tags: descriptor.Tags, SupportedEcosystems: descriptor.SupportedEcosystems, SupportedManagers: descriptor.SupportedManagers, Requires: descriptor.Requires} } func cloneDetectorDescriptor(descriptor *sdkplugin.DetectorDescriptor) *sdkplugin.DetectorDescriptor { @@ -1013,13 +1048,7 @@ func cloneMatcherDescriptor(descriptor *sdkplugin.MatcherDescriptor) *sdkplugin. if descriptor == nil { return nil } - copyValue := *descriptor - copyValue.SupportedEcosystems = append([]model.Ecosystem(nil), descriptor.SupportedEcosystems...) - copyValue.SupportedManagers = append([]model.PackageManager(nil), descriptor.SupportedManagers...) - copyValue.Aliases = append([]string(nil), descriptor.Aliases...) - copyValue.Tags = append([]string(nil), descriptor.Tags...) - copyValue.Capabilities = append([]string(nil), descriptor.Capabilities...) - copyValue.ConfigSchema = append(json.RawMessage(nil), descriptor.ConfigSchema...) + copyValue := descriptor.Clone() return ©Value } @@ -1027,12 +1056,7 @@ func cloneAuditorDescriptor(descriptor *sdkplugin.AuditorDescriptor) *sdkplugin. if descriptor == nil { return nil } - copyValue := *descriptor - copyValue.SupportedEcosystems = append([]model.Ecosystem(nil), descriptor.SupportedEcosystems...) - copyValue.SupportedManagers = append([]model.PackageManager(nil), descriptor.SupportedManagers...) - copyValue.Aliases = append([]string(nil), descriptor.Aliases...) - copyValue.Tags = append([]string(nil), descriptor.Tags...) - copyValue.ConfigSchema = append(json.RawMessage(nil), descriptor.ConfigSchema...) + copyValue := descriptor.Clone() return ©Value } @@ -1040,14 +1064,6 @@ func cloneAnalyzerDescriptor(descriptor *sdkplugin.AnalyzerDescriptor) *sdkplugi if descriptor == nil { return nil } - copyValue := *descriptor - copyValue.SupportedEcosystems = append([]model.Ecosystem(nil), descriptor.SupportedEcosystems...) - copyValue.SupportedManagers = append([]model.PackageManager(nil), descriptor.SupportedManagers...) - copyValue.Aliases = append([]string(nil), descriptor.Aliases...) - copyValue.Tags = append([]string(nil), descriptor.Tags...) - copyValue.SupportedLanguages = append([]model.Language(nil), descriptor.SupportedLanguages...) - copyValue.SupportedTiers = append([]model.ReachabilityTier(nil), descriptor.SupportedTiers...) - copyValue.Capabilities = append([]string(nil), descriptor.Capabilities...) - copyValue.ConfigSchema = append(json.RawMessage(nil), descriptor.ConfigSchema...) + copyValue := descriptor.Clone() return ©Value } diff --git a/internal/plugin/verify.go b/internal/plugin/verify.go index d38edeb6..9947d738 100644 --- a/internal/plugin/verify.go +++ b/internal/plugin/verify.go @@ -65,6 +65,7 @@ func Verify(ctx context.Context, root, id string) (*VerifyResult, error) { MatcherDescriptor: installedSnapshot.MatcherDescriptor, AuditorDescriptor: installedSnapshot.AuditorDescriptor, AnalyzerDescriptor: installedSnapshot.AnalyzerDescriptor, + AccessDisclosure: manifest.AccessDisclosure(), Installed: record, Entrypoint: fullEntrypoint, }, @@ -72,6 +73,20 @@ func Verify(ctx context.Context, root, id string) (*VerifyResult, error) { }, nil } +// InstalledManifest reads and validates the manifest of one installed +// plugin, so a caller can show its access disclosure before enabling it. +func InstalledManifest(root, id string) (Manifest, error) { + root, err := resolveRoot(root) + if err != nil { + return Manifest{}, err + } + record, err := findInstalled(root, id) + if err != nil { + return Manifest{}, err + } + return readManifest(record.Path) +} + // Enable marks one installed plugin enabled. func Enable(root, id string) (*InstalledPlugin, error) { return updateInstalledPlugin(root, id, func(plugin *InstalledPlugin) error { diff --git a/internal/support/component_docs.go b/internal/support/component_docs.go index c73d9d7c..246d35b3 100644 --- a/internal/support/component_docs.go +++ b/internal/support/component_docs.go @@ -714,6 +714,9 @@ func renderPackageManagerMarkdown(ecosystem model.Ecosystem, entry registry.Pack _, _ = fmt.Fprintf(&b, "| Install-first support | %s |\n", yesNo(chainSupportsInstallFirst(entry.Detectors))) _, _ = fmt.Fprintf(&b, "| Remediation hints | %s |\n", remediationActionsForChain(entry.Detectors, entry.Manager, true)) _, _ = fmt.Fprintf(&b, "| Commands the chain may run | %s |\n", commandHintsForChain(entry.Detectors)) + if requires := chainRequirements(entry.Detectors); requires != "" { + _, _ = fmt.Fprintf(&b, "| Detector requirements | %s |\n", requires) + } b.WriteString(remediationActionFootnotes(entry.Detectors, entry.Manager)) if prose := loadProse("detectors", name); prose != "" { b.WriteString("\n") @@ -845,6 +848,9 @@ func renderMatcherMarkdown(descriptor plugin.MatcherDescriptor) string { if len(descriptor.SupportedEcosystems) > 0 { _, _ = fmt.Fprintf(&b, "| Ecosystems | %s |\n", ecosystemCodeList(descriptor.SupportedEcosystems)) } + if len(descriptor.Requires) > 0 { + _, _ = fmt.Fprintf(&b, "| Requires | %s |\n", requirementCodeList(descriptor.Requires)) + } if prose := loadProse("matchers", descriptor.Name); prose != "" { b.WriteString("\n") b.WriteString(prose) @@ -898,6 +904,9 @@ func renderAuditorMarkdown(descriptor plugin.AuditorDescriptor) string { if len(descriptor.Tags) > 0 { _, _ = fmt.Fprintf(&b, "| Tags | %s |\n", codeList(descriptor.Tags)) } + if len(descriptor.Requires) > 0 { + _, _ = fmt.Fprintf(&b, "| Requires | %s |\n", requirementCodeList(descriptor.Requires)) + } if prose := loadProse("auditors", descriptor.Name); prose != "" { b.WriteString("\n") b.WriteString(prose) @@ -1265,3 +1274,29 @@ func writeMarkdown(path, content string) error { } return nil } + +// requirementCodeList renders a descriptor's declared requirements. A +// component that declares none gets no row: its requirements are +// unspecified, which the absence of the row already says. +func requirementCodeList(requires plugin.Requirements) string { + values := make([]string, 0, len(requires)) + for _, requirement := range requires.Normalized() { + values = append(values, string(requirement)) + } + return codeList(values) +} + +// chainRequirements renders the requirements each detector in a chain +// declares, as "detector: tokens" entries; empty when none declares any. +func chainRequirements(detectorNames []string) string { + byName := builtinDetectorsByName() + var entries []string + for _, name := range detectorNames { + detector, ok := byName[name] + if !ok || len(detector.Descriptor().Requires) == 0 { + continue + } + entries = append(entries, fmt.Sprintf("`%s`: %s", name, requirementCodeList(detector.Descriptor().Requires))) + } + return strings.Join(entries, "; ") +} diff --git a/internal/support/docs_gen_test.go b/internal/support/docs_gen_test.go index e0fbc933..7debaddc 100644 --- a/internal/support/docs_gen_test.go +++ b/internal/support/docs_gen_test.go @@ -5,6 +5,8 @@ import ( "path/filepath" "strings" "testing" + + "github.com/bomly-dev/bomly-sdk/plugin" ) func TestGenerateDocsWritesAllArtifacts(t *testing.T) { @@ -85,3 +87,17 @@ func TestGenerateDocsIsDeterministic(t *testing.T) { } } } + +func TestComponentDocsListDeclaredRequirements(t *testing.T) { + requires := plugin.Requirements{plugin.RequirementVulnerabilityRecords, plugin.RequirementSourceTree} + matcher := renderMatcherMarkdown(plugin.MatcherDescriptor{Name: "example", Requires: requires}) + auditor := renderAuditorMarkdown(plugin.AuditorDescriptor{Name: "example", Requires: requires}) + for name, page := range map[string]string{"matcher": matcher, "auditor": auditor} { + if !strings.Contains(page, "| Requires | `source-tree-v1`, `vulnerability-records-v1` |") { + t.Errorf("%s page must list declared requirements, sorted:\n%s", name, page) + } + } + if page := renderMatcherMarkdown(plugin.MatcherDescriptor{Name: "example"}); strings.Contains(page, "| Requires |") { + t.Errorf("a component that declares nothing gets no requirements row:\n%s", page) + } +} From 3df92642784329237721aeca9209879e3eddd22b Mon Sep 17 00:00:00 2001 From: Ahmed ElMallah Date: Sun, 25 Oct 2026 01:05:00 -0700 Subject: [PATCH 04/10] docs: ADR-0051 and plugin docs for component prerequisites and declared access ADR-0051 records the requirement vocabulary the host evaluates, unknown tokens, explicit-versus-default failure, why provider names are not a requirement, and disclosure without enforcement. docs/PLUGINS.md gains "Component prerequisites" and "Declared access"; the authoring guide lists the access keys and the descriptor's requires list. Closes bomly-dev/bomly-cli#417 Closes bomly-dev/bomly-cli#418 Co-Authored-By: Claude Opus 5.5 --- dev-docs/ARCHITECTURE.md | 4 +- ...s-are-evaluated-or-shown-never-enforced.md | 57 +++++++++++++++++++ dev-docs/adr/README.md | 1 + docs/PLUGINS.md | 56 +++++++++++++++++- docs/plugins/authoring.md | 25 +++++++- 5 files changed, 139 insertions(+), 4 deletions(-) create mode 100644 dev-docs/adr/0051-component-declarations-are-evaluated-or-shown-never-enforced.md diff --git a/dev-docs/ARCHITECTURE.md b/dev-docs/ARCHITECTURE.md index e63b0c81..4a212b74 100644 --- a/dev-docs/ARCHITECTURE.md +++ b/dev-docs/ARCHITECTURE.md @@ -92,6 +92,8 @@ Stage summary: `bomly explain` reuses the same detection (resolution + consolidation) and matching stages, then performs dependency path selection in its explain orchestration before optional component audit. +Every stage starts with a preflight (`internal/engine/preflight.go`). It compares the requirements each selected component's descriptor declares (`sdk.Requirements`: a source tree, a dependency graph, vulnerability records) with what the target and the earlier stages actually produced. Before detection starts, an explicitly selected component that the plan can never satisfy fails the command. Inside a stage, a component whose requirement the data does not meet is left out of a registry view for that stage and reported on the stage's warning channel, before its `Ready` is called. Components that declare nothing are untouched, and preflight never reorders stages or resolves a provider by name ([ADR-0051](adr/0051-component-declarations-are-evaluated-or-shown-never-enforced.md)). + ## Extensibility Extensibility is the core of Bomly's design. **Every built-in is an implementation of the same contract an external plugin implements** — there is no privileged internal path. Adding an ecosystem, an enrichment source, or a policy gate does not require forking the engine. Three extension points are pluggable today (detector, matcher, auditor); external **analyzer** plugins are planned — the built-in reachability analyzers are not yet loadable as plugins. @@ -304,7 +306,7 @@ Managed plugin installation is owned by Bomly rather than by the runtime library 1. Resolve a local archive, local dev binary, or direct URL source. 2. Validate checksums when required. 3. Extract archives safely into a temp directory. -4. Validate `bomly-plugin.json`. +4. Validate `bomly-plugin.json`, including its optional `access` block through `sdk.ValidateAccess`. The block is the publisher's disclosure, shown on install and enable and never enforced; an absent block is unknown, not "no access". 5. Start the plugin through the SDK/gRPC runtime, fetch the role descriptor named by the manifest kind, require `descriptor.name == manifest.id`, and store Bomly's internal descriptor snapshot. 6. Move the plugin into `~/.bomly/plugins/store//`. 7. Update `installed.json` atomically. diff --git a/dev-docs/adr/0051-component-declarations-are-evaluated-or-shown-never-enforced.md b/dev-docs/adr/0051-component-declarations-are-evaluated-or-shown-never-enforced.md new file mode 100644 index 00000000..a07effee --- /dev/null +++ b/dev-docs/adr/0051-component-declarations-are-evaluated-or-shown-never-enforced.md @@ -0,0 +1,57 @@ +# ADR-0051: Component declarations are evaluated or shown, never enforced + +- **Date:** 2026-10-25 +- **Status:** Accepted + +## Context + +`Ready` and `Applicable` run only after selection, so an impossible plan (a +reachability analyzer on an SBOM document) failed late, and docs could not +say what a component needs. A managed plugin runs with the user's +authority, but its manifest could not say what access it expects. +bomly-sdk v0.16.0 added descriptor `Requires` (versioned data tokens) and a +manifest `Access` block. + +## Decision + +- The SDK owns the types, vocabulary, normalization and validation + (`Requirements.Unsatisfied`, `ValidateAccess`). The CLI owns evaluation + and presentation, and duplicates no validator. +- The host vouches for `source-tree-v1` when the target is a path or Git + checkout not planned as an SBOM document. It vouches for + `dependency-graph-v1` after detection, when the graph holds a dependency + node. It vouches for `vulnerability-records-v1` at analyze and audit, when + the registry carries a vulnerability record. That last one is observed, + because no descriptor says which matcher produces records. A token the + host cannot evaluate is never satisfied. +- Before any stage, an explicitly selected component fails the command + (exit 4) when the plan can never meet its requirement: wrong target + shape, unknown token, or data no earlier stage produces. Explicit means + named in a plain selector list, or default-off and added with `+name`. + The error names the component, the requirement and the remedy. +- At each stage, any component whose requirement the actual data misses is + held back before `Ready`, with a warning on that stage's channel. This + applies to explicit components too, since the input, not the selection, + lacks the data. +- Passing components still face `Ready` and `Applicable`. An absent + `Requires` is legacy and untouched. +- `Access` is shown as the publisher's unverified claim on install, on + enable (before enabling), and in info, verify, doctor and JSON + (`accessDisclosure`). An absent block is unknown and unrestricted. + +## Rejected + +Named provider dependencies with a scheduler: they make the fixed pipeline +a service graph, and a token shaped like a component name is only an unknown token. Failing an +explicit component on empty data would fail CI on a project with no +vulnerabilities. Enforcing access needs a sandbox, and a declaration is not +evidence of behavior. + +## Consequences + +- No built-in declares requirements yet, so current runs are unchanged. +- A new token needs an evaluator change here before it can ever pass. +- No output claims enforcement. + +Enforced by: `internal/engine/preflight_test.go`, +`internal/plugin/access_test.go`, `internal/cli/plugin_access_test.go`. diff --git a/dev-docs/adr/README.md b/dev-docs/adr/README.md index 444bb43d..5a074124 100644 --- a/dev-docs/adr/README.md +++ b/dev-docs/adr/README.md @@ -75,6 +75,7 @@ The rule itself is [ADR-0034](0034-decisions-are-recorded-as-individual-adrs.md) | ADR-0047 | 2026-10-03 | [Release assurance is a catalog plus a per-check result contract](0047-release-assurance-is-a-catalog-and-a-result-contract.md) | | ADR-0048 | 2026-10-19 | [OSV stays opt-in; Grype keeps its database fresh](0048-osv-stays-opt-in-and-grype-keeps-its-database-fresh.md) | | ADR-0049 | 2026-10-19 | [A pinned origin is one VCS locator in every export](0049-a-pinned-origin-is-one-vcs-locator-in-every-export.md) | +| ADR-0051 | 2026-10-25 | [Component declarations are evaluated or shown, never enforced](0051-component-declarations-are-evaluated-or-shown-never-enforced.md) | ## Retired diff --git a/docs/PLUGINS.md b/docs/PLUGINS.md index 69521054..149ca7e8 100644 --- a/docs/PLUGINS.md +++ b/docs/PLUGINS.md @@ -100,6 +100,36 @@ bomly scan --enrich --analyze --analyzers +my-reach-analyzer # add an analyz A detector plugin takes part in project discovery like a built-in detector. It declares which package managers and files it handles, which directories to skip, and whether it expands workspace modules itself; see [Monorepos](MONOREPOS.md). +## Component prerequisites + +A component can declare the inputs it needs before it can do useful work. Bomly checks these declarations before it calls the component. A component that passes still runs its own readiness and applicability checks, so a declaration never makes a component run where it would not have run before. A component that declares nothing runs exactly as it always has. + +| Requirement | Met when | +| --- | --- | +| `source-tree-v1` | The target is a directory (`--path`) or a Git repository (`--url`), not an SBOM document or a container image | +| `dependency-graph-v1` | Detection found at least one dependency. A detector cannot require it | +| `vulnerability-records-v1` | At least one package carries a vulnerability record when analyzers and auditors run. This usually needs `--enrich` with a vulnerability [matcher](GLOSSARY.md) | + +What Bomly does with an unmet requirement depends on why the component is in the run: + +| Situation | Result | +| --- | --- | +| You selected the component by name, and the target can never meet the requirement | The command stops with exit code 4 before any stage runs | +| The component runs by default | Bomly skips it and shows a warning under that stage | +| The requirement depends on what the scan found, such as no dependencies or no vulnerability records | Bomly skips it and shows a warning, however it was selected | + +"By name" means a plain selector list such as `--analyzers my-reach-analyzer`, or `+name` for a component that is off by default. A requirement that this version of Bomly does not know is never treated as met. + +The error names the component, the requirement, and what would meet it. This run selects an analyzer that needs a source tree while it reads an SBOM file: + +```text +bomly scan --sbom --path ./bom.cdx.json --enrich --analyze --analyzers my-reach-analyzer + +Error: selected components cannot run: analyzer my-reach-analyzer requires source-tree-v1: the target is an SBOM document, not a source tree; scan a directory with --path or a Git repository with --url +``` + +`bomly plugins info ` lists the requirements a component declares. Requirements name kinds of data, never other plugins, and Bomly never changes the order of the stages to meet one. + ## Configure a plugin Plugin configuration is grouped by component kind under `plugins..`: @@ -132,11 +162,35 @@ Before it runs a plugin, Bomly checks: Bomly cannot restrict a plugin's file or network access, stop it reading credentials from the environment, stop it starting child processes, or guarantee that an unchecked binary matches its declared source. +### Declared access + +A plugin's manifest can include an `access` block: the publisher's own statement of the files, network destinations, environment variables, and commands the plugin uses. Bomly shows it when you install the plugin, when you enable it (before the plugin is enabled), and in `bomly plugins info`, `verify`, and `doctor`. The `--json` forms of `list`, `info`, `verify`, and `doctor` carry it as `access`, with `accessDisclosure` set to `declared` or `unknown`. + +This is how `bomly plugins enable` shows a declared block: + +```text +Declared access (the publisher's claim; Bomly does not verify or enforce it): + Filesystem read : cache, project + Filesystem write : cache + Network : api.osv.dev + Environment : none declared + Subprocesses : none declared +enabled acme.matcher.example@1.0.0 +``` + +Read the block as a description, not a limit: + +- Bomly does not check that the plugin behaves as declared, and it does not stop the plugin from doing more. A checksum proves the file is the one published, not that its behavior is safe. +- A manifest without an `access` block shows `Declared access: unknown`. Treat that plugin as able to use everything your user account can. +- An `access` block with every list empty is the publisher's claim that the plugin needs none of that access. +- Bomly shows environment variable names only, never their values. +- Bomly refuses to install a manifest whose `access` block is malformed or has an unknown key, so a declaration is never shortened without notice. + Recommended practice: - Prefer `github:owner/repo@tag` installs from releases that publish `SHA256SUMS`. - Always pass `--checksum` for direct URL installs. -- Run `bomly plugins verify ` before you enable a plugin from an external source. +- Run `bomly plugins verify ` before you enable a plugin from an external source, and compare its declared access with what the plugin says it does. - Do not enable plugins you did not build or obtain from a source you control. [Security and trust boundaries](SECURITY.md) describes the wider trust model. diff --git a/docs/plugins/authoring.md b/docs/plugins/authoring.md index 1d7a23d5..2d5d8e3c 100644 --- a/docs/plugins/authoring.md +++ b/docs/plugins/authoring.md @@ -53,10 +53,31 @@ A plugin's identity lives in three places: | Place | Holds | Written by | | --- | --- | --- | -| `bomly-plugin.json` (the manifest) | Package facts: ID, name, version, description, homepage, license, source, Bomly version constraint, runtime, plugin API version, entrypoint | You | -| The descriptor the binary returns | Component facts: name, display name, aliases, tags, supported ecosystems and package managers, role-specific behavior | You, in code | +| `bomly-plugin.json` (the manifest) | Package facts: ID, name, version, description, homepage, license, source, Bomly version constraint, runtime, plugin API version, entrypoint, and an optional `access` block | You | +| The descriptor the binary returns | Component facts: name, display name, aliases, tags, supported ecosystems and package managers, optional `requires` list, role-specific behavior | You, in code | | Bomly's installed-plugin database | Checksum, enabled state, install path, and a snapshot of the descriptor | Bomly, at install time | +The descriptor's `requires` list names the inputs the component needs, such as `source-tree-v1`. Bomly checks it before the component runs; `Ready` and `Applicable` still run afterwards. The manifest's `access` block discloses the files, network destinations, environment variables, and commands the plugin uses. Bomly shows it to users before they enable the plugin and does not enforce it. Leave a list empty only when the plugin truly needs none of that access; leave the block out and users see the plugin's access as unknown. [Component prerequisites](../PLUGINS.md#component-prerequisites) and [Declared access](../PLUGINS.md#declared-access) describe both. + +The `access` block has five optional lists. Bomly sorts each list and removes duplicates when it reads the manifest: + +| Key | Entries | +| --- | --- | +| `filesystemRead`, `filesystemWrite` | Areas, not paths: `project` (the scan target), `temp`, `cache`, `home`, or `any` | +| `network` | Host names (`api.osv.dev`), a host and its subdomains (`*.github.com`), or `*` | +| `environment` | Variable names (`GITHUB_TOKEN`), a prefix (`BOMLY_HTTP_*`), or `*` | +| `subprocesses` | Command names without a path (`go`, `npm`), or `*` | + +This manifest fragment declares a matcher that reads the project and its cache, writes the cache, and calls one API: + +```json +"access": { + "filesystemRead": ["project", "cache"], + "filesystemWrite": ["cache"], + "network": ["api.osv.dev"] +} +``` + The descriptor `name` must equal the manifest `id`. For a packaged plugin, Bomly reads `id`, `kind`, and `pluginApiVersion` from the manifest, starts the binary, fetches the matching descriptor, and checks the names agree. For a `--dev` install without a manifest, Bomly asks for every role's descriptor and accepts the binary only when exactly one role answers. ## Repository layout From dd5a300c9a96c1d946c731dee60fd9e00d39c9b4 Mon Sep 17 00:00:00 2001 From: Ahmed ElMallah Date: Sun, 25 Oct 2026 01:14:13 -0700 Subject: [PATCH 05/10] fix(engine): preflight ecosystem-scoped auditors in a component audit explain's component audit selects auditors by the queried package's ecosystem, but preflight listed them with no ecosystem, so an npm-only auditor was neither checked at planning nor held back before Ready. The plan now sees every auditor the filter selects, and the component-audit stage evaluates the same selection the engine makes. Co-Authored-By: Claude Opus 5.5 --- internal/engine/pipeline.go | 10 +++---- internal/engine/preflight.go | 28 +++++++++++++++----- internal/engine/preflight_test.go | 43 ++++++++++++++++++++++++++++++- internal/registry/view.go | 14 ++++++++++ 4 files changed, 82 insertions(+), 13 deletions(-) diff --git a/internal/engine/pipeline.go b/internal/engine/pipeline.go index f63c389b..75f43754 100644 --- a/internal/engine/pipeline.go +++ b/internal/engine/pipeline.go @@ -139,7 +139,7 @@ func acceptedFindingCount(findings []model.Finding) int { // consolidates them into the single graph and package registry the rest of the // pipeline operates on. Consolidation is the tail of detection, not a separate stage. func (p *Pipeline) runDetect(ctx context.Context, result *PipelineResult, req PipelineRequest) error { - stage, issues := p.preflightStage(StageDetect, req, nil, nil) + stage, issues := p.preflightStage(StageDetect, req, stageData{}) if err := stage.runResolve(ctx, result, req); err != nil { if len(issues) > 0 { return fmt.Errorf("%w (%s)", err, preflightSummary(issues)) @@ -508,7 +508,7 @@ func (p *Pipeline) analyze(ctx context.Context, result *PipelineResult, req Pipe AnalyzerFilter: req.AnalyzerFilter, Stderr: req.Stderr, } - stage, issues := p.preflightStage(StageAnalyze, req, result.Graph, result.Registry) + stage, issues := p.preflightStage(StageAnalyze, req, stageData{graph: result.Graph, registry: result.Registry}) result.AnalyzeWarnings = append(result.AnalyzeWarnings, preflightWarnings(issues)...) analyzeResult, err := stage.engine.Analyze(ctx, aReq) result.AnalyzerRuns = analyzeResult.AnalyzerRuns @@ -548,7 +548,7 @@ func (p *Pipeline) match(ctx context.Context, result *PipelineResult, req Pipeli MatcherFilter: req.MatcherFilter, Stderr: req.Stderr, } - stage, issues := p.preflightStage(StageMatch, req, result.Graph, result.Registry) + stage, issues := p.preflightStage(StageMatch, req, stageData{graph: result.Graph, registry: result.Registry}) result.MatchWarnings = append(result.MatchWarnings, preflightWarnings(issues)...) matchResult, err := stage.engine.Match(ctx, mReq) result.MatcherStats = matchResult.MatcherStats @@ -576,7 +576,7 @@ func (p *Pipeline) audit(ctx context.Context, g *model.Graph, registry *model.Pa AuditorFilter: req.AuditorFilter, Stderr: req.Stderr, } - stage, issues := p.preflightStage(StageAudit, req, g, registry) + stage, issues := p.preflightStage(StageAudit, req, stageData{graph: g, registry: registry}) warnings := preflightWarnings(issues) result, err := stage.engine.Audit(ctx, auditReq) if err != nil { @@ -600,7 +600,7 @@ func (p *Pipeline) auditComponent(ctx context.Context, g *model.Graph, registry AuditorFilter: req.AuditorFilter, Stderr: req.Stderr, } - stage, issues := p.preflightStage(StageAudit, req, g, registry) + stage, issues := p.preflightStage(StageAudit, req, stageData{graph: g, registry: registry, ecosystem: auditReq.Ecosystem}) warnings := preflightWarnings(issues) result, err := stage.engine.Audit(ctx, auditReq) result.Findings = DeduplicateFindings(result.Findings) diff --git a/internal/engine/preflight.go b/internal/engine/preflight.go index bed42a10..cefb1331 100644 --- a/internal/engine/preflight.go +++ b/internal/engine/preflight.go @@ -230,7 +230,7 @@ func (p *Pipeline) preflightPlan(req PipelineRequest) error { var issues []PreflightIssue for _, stage := range plannedStages(req) { facts := preflightFacts{stage: stage, planning: true, target: target, matchStage: req.EnrichEnabled || req.MatchEnabled} - for _, candidate := range p.stageCandidates(stage, req) { + for _, candidate := range p.stageCandidates(stage, req, stageData{planning: true}) { if candidate.explicit { issues = append(issues, facts.issues(candidate)...) } @@ -250,20 +250,30 @@ func (p *Pipeline) preflightPlan(req PipelineRequest) error { return &PreflightError{Issues: issues} } +// stageData is what one stage run receives. ecosystem is set only by a +// component audit, which selects auditors by the queried package's +// ecosystem; planning sees every selected auditor instead. +type stageData struct { + graph *model.Graph + registry *model.PackageRegistry + ecosystem model.Ecosystem + planning bool +} + // preflightStage evaluates the components stage would run against the data // the stage actually receives. It returns the pipeline the stage runs on -- // p itself when nothing is held back, otherwise a view whose registry leaves // the held-back components out -- and one issue per unmet requirement. // Components that pass still go through Ready and Applicable as before. -func (p *Pipeline) preflightStage(stage PipelineStage, req PipelineRequest, graph *model.Graph, registry *model.PackageRegistry) (*Pipeline, []PreflightIssue) { +func (p *Pipeline) preflightStage(stage PipelineStage, req PipelineRequest, data stageData) (*Pipeline, []PreflightIssue) { facts := preflightFacts{ stage: stage, target: describeTarget(req), matchStage: req.EnrichEnabled || req.MatchEnabled, - dependencyNodes: hasDependencyNode(graph), - vulnerabilityRecords: hasVulnerabilityRecord(registry), + dependencyNodes: hasDependencyNode(data.graph), + vulnerabilityRecords: hasVulnerabilityRecord(data.registry), } - candidates := p.stageCandidates(stage, req) + candidates := p.stageCandidates(stage, req, data) var issues []PreflightIssue var skipped []string declared := 0 @@ -302,7 +312,7 @@ func (p *Pipeline) preflightStage(stage PipelineStage, req PipelineRequest, grap // stageCandidates lists the components stage would run for req, through the // same registry selection the stage itself uses, so preflight sees exactly // the plan the filters, defaults and detector chains produce. -func (p *Pipeline) stageCandidates(stage PipelineStage, req PipelineRequest) []preflightCandidate { +func (p *Pipeline) stageCandidates(stage PipelineStage, req PipelineRequest, data stageData) []preflightCandidate { reg := p.Registry kind := stageKinds[stage] var candidates []preflightCandidate @@ -343,7 +353,11 @@ func (p *Pipeline) stageCandidates(stage PipelineStage, req PipelineRequest) []p } case StageAudit: filter := req.AuditorFilter - for _, auditor := range reg.Auditors(plugin.AuditRequest{AuditorFilter: filter}) { + auditors := reg.Auditors(plugin.AuditRequest{AuditorFilter: filter, Ecosystem: data.ecosystem}) + if data.planning { + auditors = reg.SelectedAuditors(filter) + } + for _, auditor := range auditors { descriptor := auditor.Descriptor() add(descriptor.Name, descriptor.Requires, filter.Include, filter.Exclude, filter.Includes) } diff --git a/internal/engine/preflight_test.go b/internal/engine/preflight_test.go index a4b12cee..26542b26 100644 --- a/internal/engine/preflight_test.go +++ b/internal/engine/preflight_test.go @@ -412,7 +412,7 @@ func TestPreflight_EmptyRegistryPlansNothing(t *testing.T) { t.Fatalf("an empty registry has nothing to reject, got %v", err) } for _, stage := range plannedStages(req) { - stagePipeline, issues := pipeline.preflightStage(stage, req, nil, nil) + stagePipeline, issues := pipeline.preflightStage(stage, req, stageData{}) if stagePipeline != pipeline || len(issues) != 0 { t.Fatalf("stage %s: nothing to hold back, got %v", stage, issues) } @@ -497,3 +497,44 @@ func TestPreflight_OperatorSelectedDefaultOffComponentIsExplicit(t *testing.T) { t.Fatalf("a default-off component added with +name is the user's explicit choice, got %v", err) } } + +func TestPreflight_ComponentAuditChecksEcosystemScopedAuditors(t *testing.T) { + // A component audit selects auditors by the queried package's ecosystem, + // so an npm-only auditor runs there although a plain audit would never + // select it. Preflight must see it on both the plan and the stage. + graph := model.New() + app := testnodes.DepFrom(model.DependencyNode{Coordinates: model.Coordinates{Ecosystem: "npm", Name: "app", Version: "1.0.0", PURL: "pkg:npm/app@1.0.0"}}) + dep := testnodes.DepFrom(model.DependencyNode{Coordinates: model.Coordinates{Ecosystem: "npm", Name: "dep", Version: "2.0.0", PURL: "pkg:npm/dep@2.0.0"}}) + for _, node := range []*model.DependencyNode{app, dep} { + if err := graph.AddNode(node); err != nil { + t.Fatalf("add node: %v", err) + } + } + if err := graph.AddEdge(app.NodeID(), dep.NodeID()); err != nil { + t.Fatalf("add edge: %v", err) + } + registry, req := preflightScenario(t, graph) + auditor := &calls{} + registry.registerAuditor(preflightAuditor{ + descriptor: plugin.AuditorDescriptor{Name: "npm-only", SupportedEcosystems: []model.Ecosystem{model.EcosystemNPM}, Requires: requires("future-input-v1")}, + calls: auditor, + }) + req.AuditEnabled = true + + result, err := NewPipeline(registry, zap.NewNop()).RunExplain(context.Background(), ExplainRequest{Query: "dep", Pipeline: req}) + if err != nil { + t.Fatalf("RunExplain() error = %v", err) + } + if *auditor != (calls{}) { + t.Fatalf("the component audit must hold the auditor back before Ready, got %+v", *auditor) + } + if len(result.AuditWarnings) == 0 || result.AuditWarnings[0].Source != "npm-only" { + t.Fatalf("expected a diagnostic for the held-back auditor, got %v", result.AuditWarnings) + } + + req.AuditorFilter = plugin.AuditorFilter{Include: []string{"npm-only"}} + _, err = NewPipeline(registry, zap.NewNop()).RunExplain(context.Background(), ExplainRequest{Query: "dep", Pipeline: req}) + if _, ok := errors.AsType[*PreflightError](err); !ok { + t.Fatalf("an explicitly selected ecosystem-scoped auditor that can never run must fail the plan, got %v", err) + } +} diff --git a/internal/registry/view.go b/internal/registry/view.go index ccc7badc..780491bf 100644 --- a/internal/registry/view.go +++ b/internal/registry/view.go @@ -12,6 +12,20 @@ func (r *Registry) DefaultEnabled(kind plugin.PluginKind, name string) bool { return r.isDefaultEnabled(kind, name) } +// SelectedAuditors returns every auditor filter selects, before ecosystem +// and package-manager matching narrows the set for one request. A component +// audit selects by the queried package's ecosystem, which planning cannot +// know in advance, so planning has to see all of them. +func (r *Registry) SelectedAuditors(filter plugin.AuditorFilter) []plugin.Auditor { + selected := make([]plugin.Auditor, 0, len(r.auditors)) + for _, auditor := range r.auditors { + if r.auditorSelected(filter, auditor.Descriptor()) { + selected = append(selected, auditor) + } + } + return selected +} + // Without returns a view of the registry that leaves out the named // components of one kind and shares every other registration. Runtime // preflight uses it to hold a component back from a stage without touching From 9e71bacb2ea71f784d12c7588262cb45a834c6c9 Mon Sep 17 00:00:00 2001 From: Ahmed ElMallah Date: Sun, 25 Oct 2026 01:23:50 -0700 Subject: [PATCH 06/10] fix: address CodeRabbit round 1 on preflight and access disclosure - explain reports a preflight skip once, not once per matching manifest. - LoadRuntimePlugins sets accessDisclosure like the other installed loaders. - An absent access block reads "has no access declaration", which cannot be mistaken for an empty declaration. - PLUGINS.md and the authoring guide state when Ready and Applicable run, and what a refused install says; ADR index count and ADR-0051 trimmed. Co-Authored-By: Claude Opus 5.5 --- ...ns-are-evaluated-or-shown-never-enforced.md | 6 ++---- dev-docs/adr/README.md | 2 +- docs/PLUGINS.md | 4 ++-- docs/plugins/authoring.md | 4 +++- internal/cli/plugin_access.go | 5 +++-- internal/cli/plugin_access_test.go | 2 +- internal/engine/pipeline_explain.go | 13 ++++++++++++- internal/engine/preflight_test.go | 18 ++++++++++++++++-- internal/plugin/types.go | 1 + 9 files changed, 41 insertions(+), 14 deletions(-) diff --git a/dev-docs/adr/0051-component-declarations-are-evaluated-or-shown-never-enforced.md b/dev-docs/adr/0051-component-declarations-are-evaluated-or-shown-never-enforced.md index a07effee..f5a531c9 100644 --- a/dev-docs/adr/0051-component-declarations-are-evaluated-or-shown-never-enforced.md +++ b/dev-docs/adr/0051-component-declarations-are-evaluated-or-shown-never-enforced.md @@ -14,9 +14,8 @@ manifest `Access` block. ## Decision -- The SDK owns the types, vocabulary, normalization and validation - (`Requirements.Unsatisfied`, `ValidateAccess`). The CLI owns evaluation - and presentation, and duplicates no validator. +- The SDK owns the types, vocabulary and validation. The CLI owns + evaluation and presentation, and duplicates no validator. - The host vouches for `source-tree-v1` when the target is a path or Git checkout not planned as an SBOM document. It vouches for `dependency-graph-v1` after detection, when the graph holds a dependency @@ -28,7 +27,6 @@ manifest `Access` block. (exit 4) when the plan can never meet its requirement: wrong target shape, unknown token, or data no earlier stage produces. Explicit means named in a plain selector list, or default-off and added with `+name`. - The error names the component, the requirement and the remedy. - At each stage, any component whose requirement the actual data misses is held back before `Ready`, with a warning on that stage's channel. This applies to explicit components too, since the input, not the selection, diff --git a/dev-docs/adr/README.md b/dev-docs/adr/README.md index 5a074124..6bb71bc9 100644 --- a/dev-docs/adr/README.md +++ b/dev-docs/adr/README.md @@ -2,7 +2,7 @@ An ADR records a choice Bomly made between viable alternatives, so the next person who proposes the other alternative finds the reasoning instead of -re-deriving it. The directory holds 21 live records and the stubs of 28 +re-deriving it. The directory holds 22 live records and the stubs of 28 retired ones; the full text of a retired record is in git history. ## When to write one diff --git a/docs/PLUGINS.md b/docs/PLUGINS.md index 149ca7e8..f5e49c87 100644 --- a/docs/PLUGINS.md +++ b/docs/PLUGINS.md @@ -102,7 +102,7 @@ A detector plugin takes part in project discovery like a built-in detector. It d ## Component prerequisites -A component can declare the inputs it needs before it can do useful work. Bomly checks these declarations before it calls the component. A component that passes still runs its own readiness and applicability checks, so a declaration never makes a component run where it would not have run before. A component that declares nothing runs exactly as it always has. +A component can declare the inputs it needs before it can do useful work. Bomly checks these declarations before it calls the component. When the declarations pass, Bomly still runs the component's own readiness and applicability checks. A component without declarations goes straight to those checks. | Requirement | Met when | | --- | --- | @@ -184,7 +184,7 @@ Read the block as a description, not a limit: - A manifest without an `access` block shows `Declared access: unknown`. Treat that plugin as able to use everything your user account can. - An `access` block with every list empty is the publisher's claim that the plugin needs none of that access. - Bomly shows environment variable names only, never their values. -- Bomly refuses to install a manifest whose `access` block is malformed or has an unknown key, so a declaration is never shortened without notice. +- Bomly refuses to install a manifest whose `access` block is malformed or has an unknown key. The install error names the problem. Recommended practice: diff --git a/docs/plugins/authoring.md b/docs/plugins/authoring.md index 2d5d8e3c..452d71eb 100644 --- a/docs/plugins/authoring.md +++ b/docs/plugins/authoring.md @@ -57,7 +57,9 @@ A plugin's identity lives in three places: | The descriptor the binary returns | Component facts: name, display name, aliases, tags, supported ecosystems and package managers, optional `requires` list, role-specific behavior | You, in code | | Bomly's installed-plugin database | Checksum, enabled state, install path, and a snapshot of the descriptor | Bomly, at install time | -The descriptor's `requires` list names the inputs the component needs, such as `source-tree-v1`. Bomly checks it before the component runs; `Ready` and `Applicable` still run afterwards. The manifest's `access` block discloses the files, network destinations, environment variables, and commands the plugin uses. Bomly shows it to users before they enable the plugin and does not enforce it. Leave a list empty only when the plugin truly needs none of that access; leave the block out and users see the plugin's access as unknown. [Component prerequisites](../PLUGINS.md#component-prerequisites) and [Declared access](../PLUGINS.md#declared-access) describe both. +The descriptor's `requires` list names the inputs the component needs, such as `source-tree-v1`. Bomly checks it before the component runs. When every requirement is met, `Ready` and `Applicable` run as usual. When one is not, Bomly skips the component or stops the command; see the link below. + +The manifest's `access` block discloses the files, network destinations, environment variables, and commands the plugin uses. Bomly shows it to users before they enable the plugin and does not enforce it. Leave a list empty only when the plugin needs none of that access. Without the block, users see the plugin's access as unknown. [Component prerequisites](../PLUGINS.md#component-prerequisites) and [Declared access](../PLUGINS.md#declared-access) describe both. The `access` block has five optional lists. Bomly sorts each list and removes duplicates when it reads the manifest: diff --git a/internal/cli/plugin_access.go b/internal/cli/plugin_access.go index 2cf1729e..604bd572 100644 --- a/internal/cli/plugin_access.go +++ b/internal/cli/plugin_access.go @@ -22,8 +22,9 @@ import ( func renderAccessDisclosure(w io.Writer, access *plugin.Access) error { if access == nil { _, err := fmt.Fprint(w, "Declared access: unknown\n"+ - " The manifest declares no access. Assume the plugin can use everything your\n"+ - " user account can: files, network, environment variables, and child processes.\n") + " The manifest has no access declaration. Assume the plugin can use everything\n"+ + " your user account can: files, network, environment variables, and child\n"+ + " processes.\n") return err } rows := [][2]string{ diff --git a/internal/cli/plugin_access_test.go b/internal/cli/plugin_access_test.go index d3f2d596..556a8611 100644 --- a/internal/cli/plugin_access_test.go +++ b/internal/cli/plugin_access_test.go @@ -44,7 +44,7 @@ func TestRenderAccessDisclosureLabelsTheClaimAsUnverified(t *testing.T) { if err := renderAccessDisclosure(&unknown, nil); err != nil { t.Fatalf("renderAccessDisclosure(nil) error = %v", err) } - if !strings.Contains(unknown.String(), "Declared access: unknown") || !strings.Contains(unknown.String(), "can use everything your") { + if !strings.Contains(unknown.String(), "Declared access: unknown") || !strings.Contains(unknown.String(), "can use everything") { t.Fatalf("a manifest without an access block must read as unknown and unrestricted, got:\n%s", unknown.String()) } for _, output := range []string{declared.String(), unknown.String()} { diff --git a/internal/engine/pipeline_explain.go b/internal/engine/pipeline_explain.go index d5ba948a..f5caa31c 100644 --- a/internal/engine/pipeline_explain.go +++ b/internal/engine/pipeline_explain.go @@ -74,7 +74,9 @@ func (p *Pipeline) RunExplain(ctx context.Context, req ExplainRequest) (ExplainR auditResult, warnings := p.auditComponent(ctx, g, base.Registry, dependency, pipeReq) findings = auditResult.Findings allFindings = append(allFindings, findings...) - result.AuditWarnings = append(result.AuditWarnings, warnings...) + // One audit runs per matching manifest, so a warning that holds + // for all of them (a preflight skip, say) is reported once. + result.AuditWarnings = appendUniqueWarnings(result.AuditWarnings, warnings...) result.AuditorRuns = appendUnique(result.AuditorRuns, auditResult.AuditorRuns...) for name, count := range auditResult.AuditorFindings { auditorFindings[name] += count @@ -135,3 +137,12 @@ func appendUnique(values []string, candidates ...string) []string { } return values } + +func appendUniqueWarnings(values []PipelineWarning, candidates ...PipelineWarning) []PipelineWarning { + for _, candidate := range candidates { + if !slices.Contains(values, candidate) { + values = append(values, candidate) + } + } + return values +} diff --git a/internal/engine/preflight_test.go b/internal/engine/preflight_test.go index 26542b26..1a23dc74 100644 --- a/internal/engine/preflight_test.go +++ b/internal/engine/preflight_test.go @@ -520,6 +520,11 @@ func TestPreflight_ComponentAuditChecksEcosystemScopedAuditors(t *testing.T) { calls: auditor, }) req.AuditEnabled = true + // A second subproject with the same dependency: explain audits once per + // manifest, and the skip must still be reported once. + second := req.Subprojects[0] + second.RelativePath = "web" + req.Subprojects = append(req.Subprojects, second) result, err := NewPipeline(registry, zap.NewNop()).RunExplain(context.Background(), ExplainRequest{Query: "dep", Pipeline: req}) if err != nil { @@ -528,8 +533,17 @@ func TestPreflight_ComponentAuditChecksEcosystemScopedAuditors(t *testing.T) { if *auditor != (calls{}) { t.Fatalf("the component audit must hold the auditor back before Ready, got %+v", *auditor) } - if len(result.AuditWarnings) == 0 || result.AuditWarnings[0].Source != "npm-only" { - t.Fatalf("expected a diagnostic for the held-back auditor, got %v", result.AuditWarnings) + if len(result.Targets) != 2 { + t.Fatalf("expected the dependency in both manifests, got %d targets", len(result.Targets)) + } + skips := 0 + for _, warning := range result.AuditWarnings { + if warning.Source == "npm-only" { + skips++ + } + } + if skips != 1 { + t.Fatalf("expected one diagnostic for the held-back auditor across both manifests, got %v", result.AuditWarnings) } req.AuditorFilter = plugin.AuditorFilter{Include: []string{"npm-only"}} diff --git a/internal/plugin/types.go b/internal/plugin/types.go index be6e62ed..c2584d07 100644 --- a/internal/plugin/types.go +++ b/internal/plugin/types.go @@ -863,6 +863,7 @@ func LoadRuntimePlugins(root string) ([]Info, error) { MatcherDescriptor: cloneMatcherDescriptor(snapshot.MatcherDescriptor), AuditorDescriptor: cloneAuditorDescriptor(snapshot.AuditorDescriptor), AnalyzerDescriptor: cloneAnalyzerDescriptor(snapshot.AnalyzerDescriptor), + AccessDisclosure: manifest.AccessDisclosure(), Installed: new(item), Enabled: item.Enabled, Entrypoint: fullEntrypoint, From 0756a707a44994ae824f3dfe5fb31952e22f5f53 Mon Sep 17 00:00:00 2001 From: Ahmed ElMallah Date: Sun, 25 Oct 2026 12:48:10 -0700 Subject: [PATCH 07/10] docs(adr): fold ADR-0050 and ADR-0051 into existing records Neither record met the ADR bar: ADR-0050's reason already lives in Engine.Match's doc comment and the SDK Clone docs, and ADR-0051 mostly described the code and restated ADR-0040's ownership split. Both are deleted. ADR-0050 landed with #532 and nothing relied on it, so it has no retired stub. The two points that pass the bar move to existing homes. ADR-0020, the live trust record, is revised in place: a manifest access block is the publisher's unverified claim, shown before enabling and never enforced. dev-docs/ARCHITECTURE.md (Scan Pipeline) now records why only a plan that can never be satisfied fails the command, and why each matcher and analyzer call works on its own snapshot. Code references point there; the ADR index is back to 21 live records. Co-Authored-By: Claude Opus 5.5 --- dev-docs/ARCHITECTURE.md | 4 +- ...y-configuration-requires-explicit-trust.md | 11 +++- ...t-call-is-a-transaction-over-a-snapshot.md | 54 ------------------ ...s-are-evaluated-or-shown-never-enforced.md | 55 ------------------- dev-docs/adr/README.md | 4 +- internal/engine/engine.go | 18 +++--- internal/engine/engine_test.go | 2 +- internal/engine/match_eligibility_test.go | 2 +- internal/engine/preflight.go | 3 +- 9 files changed, 26 insertions(+), 127 deletions(-) delete mode 100644 dev-docs/adr/0050-a-component-call-is-a-transaction-over-a-snapshot.md delete mode 100644 dev-docs/adr/0051-component-declarations-are-evaluated-or-shown-never-enforced.md diff --git a/dev-docs/ARCHITECTURE.md b/dev-docs/ARCHITECTURE.md index 4a212b74..a6bac864 100644 --- a/dev-docs/ARCHITECTURE.md +++ b/dev-docs/ARCHITECTURE.md @@ -92,7 +92,9 @@ Stage summary: `bomly explain` reuses the same detection (resolution + consolidation) and matching stages, then performs dependency path selection in its explain orchestration before optional component audit. -Every stage starts with a preflight (`internal/engine/preflight.go`). It compares the requirements each selected component's descriptor declares (`sdk.Requirements`: a source tree, a dependency graph, vulnerability records) with what the target and the earlier stages actually produced. Before detection starts, an explicitly selected component that the plan can never satisfy fails the command. Inside a stage, a component whose requirement the data does not meet is left out of a registry view for that stage and reported on the stage's warning channel, before its `Ready` is called. Components that declare nothing are untouched, and preflight never reorders stages or resolves a provider by name ([ADR-0051](adr/0051-component-declarations-are-evaluated-or-shown-never-enforced.md)). +Every stage starts with a preflight (`internal/engine/preflight.go`). It compares the requirements each selected component's descriptor declares (`sdk.Requirements`: a source tree, a dependency graph, vulnerability records) with what the target and the earlier stages actually produced. Before detection starts, an explicitly selected component that the plan can never satisfy fails the command. Inside a stage, a component whose requirement the data does not meet is left out of a registry view for that stage and reported on the stage's warning channel, before its `Ready` is called. Components that declare nothing are untouched, and preflight never reorders stages or resolves a provider by name. Only a plan that can never be satisfied fails, with exit code 4. Data that turns out to be missing at run time only skips the component, because failing an explicit component then would fail CI on a project with no vulnerabilities. A requirement token this host does not know is never satisfied. + +Each matcher and analyzer call is a transaction over a snapshot. Every `Ready`, `Applicable` and action call receives its own request clone, and only a successful result is committed: a returned registry, or else its package updates. A managed plugin's request crosses the wire as a copy, and an embedded component must not behave differently from one, so changes a component makes to the graph or target are never kept. Embedded components live as long as the command: they are constructed under its context, and `Registry.Close` runs their cleanups in the command's cleanup chain. ## Extensibility diff --git a/dev-docs/adr/0020-repository-configuration-requires-explicit-trust.md b/dev-docs/adr/0020-repository-configuration-requires-explicit-trust.md index e10fb49f..f1ccbc56 100644 --- a/dev-docs/adr/0020-repository-configuration-requires-explicit-trust.md +++ b/dev-docs/adr/0020-repository-configuration-requires-explicit-trust.md @@ -2,6 +2,7 @@ - **Date:** 2026-07-25 - **Revised:** 2026-10-19 (folds ADR-0003 and ADR-0019) +- **Revised:** 2026-10-25 (adds plugin access disclosure) - **Status:** Accepted ## Context @@ -35,11 +36,16 @@ users expect them to apply without flags. several participate, the least suppressive decision wins. No baseline-specific stage or output model exists: a suppressed finding is an ordinary finding with `policy_status: suppressed`. +- A managed plugin's manifest `access` block is the publisher's unverified + claim. Bomly shows it before the plugin is enabled and never enforces it. + An absent block means unknown and unrestricted, never "needs no access". ## Rejected Auto-loading repository configuration behind an allowlist of safe keys (the -allowlist becomes the attack surface); a separate baseline pipeline stage. +allowlist becomes the attack surface); a separate baseline pipeline stage; +enforcing declared plugin access, which needs a sandbox, when a declaration +is not evidence of behavior. ## Consequences @@ -47,4 +53,5 @@ allowlist becomes the attack surface); a separate baseline pipeline stage. - Baseline selection is visible in logs and run statistics. Enforced by: `internal/config/validate_test.go`; the symlink tests in -`internal/baseline`. +`internal/baseline`; `internal/plugin/access_test.go` and +`internal/cli/plugin_access_test.go`. diff --git a/dev-docs/adr/0050-a-component-call-is-a-transaction-over-a-snapshot.md b/dev-docs/adr/0050-a-component-call-is-a-transaction-over-a-snapshot.md deleted file mode 100644 index 9442b798..00000000 --- a/dev-docs/adr/0050-a-component-call-is-a-transaction-over-a-snapshot.md +++ /dev/null @@ -1,54 +0,0 @@ -# ADR-0050: A component call is a transaction over a snapshot, within the command's lifetime - -- **Date:** 2026-10-25 -- **Status:** Accepted - -## Context - -The same SDK module behaved differently depending on how it ran. A managed -plugin's request crosses the wire as a copy, and its result is applied only -when the RPC succeeds. An embedded matcher or analyzer received the host's own -graph, registry and target pointers, so one that changed them and then failed --- the reachability analyzers enrich `req.Registry` in place -- left the -pipeline half-enriched. Lifetimes diverged too: embedded constructors ran -under `context.Background()` with no way to release what they acquired, and a -managed component was torn down only as a side effect of killing its process. - -## Decision - -- Every `Ready`, `Applicable` and `Match`/`Analyze` call receives its own - `MatchRequest.Clone` / `AnalyzeRequest.Clone`. No component holds the host's - state. -- Only a successful action is committed: a returned `Registry` wins, otherwise - `PackageUpdates` merge through `model.ApplyPackageUpdates`. A failed call, or - one that returns after the command was cancelled, commits nothing. Rollback - is per call; earlier successes stand. -- Changes a component makes to the graph or target are never committed, as - they never were for a managed plugin. -- An embedded component is constructed under the command's context and gets a - `plugin.ComponentScope`. `Registry.Close` ends every scope, newest first, in - the command's cleanup chain ahead of temp-dir cleanup. A managed component's - scope closes when go-plugin's `Kill` shuts the plugin down gracefully, and the - pool shuts plugins down concurrently, so the command waits one grace period. - -## Rejected - -Letting embedded components keep mutating the request, documented as a -feature, was rejected: it makes rollback depend on how a plugin is packaged. -Instead the cost of one snapshot per call is accepted, measured at under 1 ms -for 500 packages. - -## Consequences - -- A component that relied on mutating the graph or target to communicate must - return a registry or deltas instead. -- Snapshots cost time and memory per call. That is the price of parity, and - it is the first place to look if a very large scan slows. -- A component's cleanups run even when its constructor fails after - registering them. - -Enforced by: `TestEngineMatchCommitsOnlySuccessfulCalls`, -`TestEngineAnalyzeCommitsOnlySuccessfulCalls` (embedded and simulated-wire -parity), `TestEngineMatchDiscardsWorkFinishedAfterCancellation`, -`TestRegistryComponentLifetimeIsTheCommands`, and bomly-sdk's conformance -probe of a managed cleanup on shutdown. diff --git a/dev-docs/adr/0051-component-declarations-are-evaluated-or-shown-never-enforced.md b/dev-docs/adr/0051-component-declarations-are-evaluated-or-shown-never-enforced.md deleted file mode 100644 index f5a531c9..00000000 --- a/dev-docs/adr/0051-component-declarations-are-evaluated-or-shown-never-enforced.md +++ /dev/null @@ -1,55 +0,0 @@ -# ADR-0051: Component declarations are evaluated or shown, never enforced - -- **Date:** 2026-10-25 -- **Status:** Accepted - -## Context - -`Ready` and `Applicable` run only after selection, so an impossible plan (a -reachability analyzer on an SBOM document) failed late, and docs could not -say what a component needs. A managed plugin runs with the user's -authority, but its manifest could not say what access it expects. -bomly-sdk v0.16.0 added descriptor `Requires` (versioned data tokens) and a -manifest `Access` block. - -## Decision - -- The SDK owns the types, vocabulary and validation. The CLI owns - evaluation and presentation, and duplicates no validator. -- The host vouches for `source-tree-v1` when the target is a path or Git - checkout not planned as an SBOM document. It vouches for - `dependency-graph-v1` after detection, when the graph holds a dependency - node. It vouches for `vulnerability-records-v1` at analyze and audit, when - the registry carries a vulnerability record. That last one is observed, - because no descriptor says which matcher produces records. A token the - host cannot evaluate is never satisfied. -- Before any stage, an explicitly selected component fails the command - (exit 4) when the plan can never meet its requirement: wrong target - shape, unknown token, or data no earlier stage produces. Explicit means - named in a plain selector list, or default-off and added with `+name`. -- At each stage, any component whose requirement the actual data misses is - held back before `Ready`, with a warning on that stage's channel. This - applies to explicit components too, since the input, not the selection, - lacks the data. -- Passing components still face `Ready` and `Applicable`. An absent - `Requires` is legacy and untouched. -- `Access` is shown as the publisher's unverified claim on install, on - enable (before enabling), and in info, verify, doctor and JSON - (`accessDisclosure`). An absent block is unknown and unrestricted. - -## Rejected - -Named provider dependencies with a scheduler: they make the fixed pipeline -a service graph, and a token shaped like a component name is only an unknown token. Failing an -explicit component on empty data would fail CI on a project with no -vulnerabilities. Enforcing access needs a sandbox, and a declaration is not -evidence of behavior. - -## Consequences - -- No built-in declares requirements yet, so current runs are unchanged. -- A new token needs an evaluator change here before it can ever pass. -- No output claims enforcement. - -Enforced by: `internal/engine/preflight_test.go`, -`internal/plugin/access_test.go`, `internal/cli/plugin_access_test.go`. diff --git a/dev-docs/adr/README.md b/dev-docs/adr/README.md index 5299ed80..444bb43d 100644 --- a/dev-docs/adr/README.md +++ b/dev-docs/adr/README.md @@ -2,7 +2,7 @@ An ADR records a choice Bomly made between viable alternatives, so the next person who proposes the other alternative finds the reasoning instead of -re-deriving it. The directory holds 23 live records and the stubs of 28 +re-deriving it. The directory holds 21 live records and the stubs of 28 retired ones; the full text of a retired record is in git history. ## When to write one @@ -75,8 +75,6 @@ The rule itself is [ADR-0034](0034-decisions-are-recorded-as-individual-adrs.md) | ADR-0047 | 2026-10-03 | [Release assurance is a catalog plus a per-check result contract](0047-release-assurance-is-a-catalog-and-a-result-contract.md) | | ADR-0048 | 2026-10-19 | [OSV stays opt-in; Grype keeps its database fresh](0048-osv-stays-opt-in-and-grype-keeps-its-database-fresh.md) | | ADR-0049 | 2026-10-19 | [A pinned origin is one VCS locator in every export](0049-a-pinned-origin-is-one-vcs-locator-in-every-export.md) | -| ADR-0050 | 2026-10-25 | [A component call is a transaction over a snapshot, within the command's lifetime](0050-a-component-call-is-a-transaction-over-a-snapshot.md) | -| ADR-0051 | 2026-10-25 | [Component declarations are evaluated or shown, never enforced](0051-component-declarations-are-evaluated-or-shown-never-enforced.md) | ## Retired diff --git a/internal/engine/engine.go b/internal/engine/engine.go index d5ecbd58..e91976a5 100644 --- a/internal/engine/engine.go +++ b/internal/engine/engine.go @@ -157,15 +157,15 @@ func (e *Engine) Analyze(ctx context.Context, req plugin.AnalyzeRequest) (plugin // Match runs registered matchers against the graph and returns the enriched graph. // -// Each call is a transaction over a snapshot (ADR-0050): every Ready, -// Applicable and Match call receives its own MatchRequest.Clone, so a matcher -// never holds the host's graph, registry or target. Only a successful Match -// is committed -- its Registry if it returned one, otherwise its -// PackageUpdates merged into the canonical registry -- and a failed or -// cancelled one leaves the canonical state exactly as the previous matcher -// left it. Changes a matcher makes to the graph or target are never -// committed, as they never were for a managed plugin, whose request crosses -// the wire as a copy. +// Each call is a transaction over a snapshot (dev-docs/ARCHITECTURE.md, Scan +// Pipeline): every Ready, Applicable and Match call receives its own +// MatchRequest.Clone, so a matcher never holds the host's graph, registry +// or target. Only a successful Match is committed -- its Registry if it +// returned one, otherwise its PackageUpdates merged into the canonical +// registry -- and a failed or cancelled one leaves the canonical state +// exactly as the previous matcher left it. Changes a matcher makes to the +// graph or target are never committed, as they never were for a managed +// plugin, whose request crosses the wire as a copy. func (e *Engine) Match(ctx context.Context, req plugin.MatchRequest) (MatchResult, error) { originalGraphSize := 0 if req.Graph != nil { diff --git a/internal/engine/engine_test.go b/internal/engine/engine_test.go index 34d15d85..e588eea6 100644 --- a/internal/engine/engine_test.go +++ b/internal/engine/engine_test.go @@ -250,7 +250,7 @@ func TestEngineAudit_SkipsNotReadyOrNotApplicableAuditors(t *testing.T) { } } -// --- Transactional component calls (ADR-0050) ------------------------------- +// --- Transactional component calls ------------------------------------------ // wireCopy round-trips v through JSON into out, which is what the managed // transport does to every request and result. diff --git a/internal/engine/match_eligibility_test.go b/internal/engine/match_eligibility_test.go index dfb33666..605096cf 100644 --- a/internal/engine/match_eligibility_test.go +++ b/internal/engine/match_eligibility_test.go @@ -120,7 +120,7 @@ func TestEngineMatchFiltersOccurrencesButPreservesGraphAndRegistry(t *testing.T) t.Fatalf("expected eligible internal edge to survive, children=%#v err=%v", children, err) } // Matchers see the complete registry, not one filtered like the graph -- - // as a snapshot (ADR-0050), never the host's own pointer. + // as a snapshot, never the host's own pointer. if matcher.registry == registry { t.Fatal("the matcher received the host's registry instead of a snapshot") } diff --git a/internal/engine/preflight.go b/internal/engine/preflight.go index cefb1331..69c90de2 100644 --- a/internal/engine/preflight.go +++ b/internal/engine/preflight.go @@ -17,7 +17,8 @@ import ( // action method is called. It never reorders the fixed pipeline and never // looks a provider up by name: a requirement names data, and the only // question asked is whether that data exists at that point. A component that -// declares nothing is legacy and passes untouched. ADR-0051 records the rules. +// declares nothing is legacy and passes untouched. dev-docs/ARCHITECTURE.md +// (Scan Pipeline) records why only an impossible plan fails the command. // PipelineStage names one stage of the fixed pipeline. type PipelineStage string From 7e17d1fbe94304d791b34e4643828b10e8c191b3 Mon Sep 17 00:00:00 2001 From: Ahmed ElMallah Date: Sun, 25 Oct 2026 12:50:34 -0700 Subject: [PATCH 08/10] docs(plugins): state the outcome for an unknown requirement A component selected by name with a requirement this Bomly does not know stops the command with exit code 4; a default one is skipped with a warning. Co-Authored-By: Claude Opus 5.5 --- docs/PLUGINS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/PLUGINS.md b/docs/PLUGINS.md index 3d4314b4..4c4e8445 100644 --- a/docs/PLUGINS.md +++ b/docs/PLUGINS.md @@ -118,11 +118,11 @@ What Bomly does with an unmet requirement depends on why the component is in the | Situation | Result | | --- | --- | -| You selected the component by name, and the target can never meet the requirement | The command stops with exit code 4 before any stage runs | +| You selected the component by name, and the run can never meet the requirement: the target is the wrong kind, or this version of Bomly does not know the requirement | The command stops with exit code 4 before any stage runs | | The component runs by default | Bomly skips it and shows a warning under that stage | | The requirement depends on what the scan found, such as no dependencies or no vulnerability records | Bomly skips it and shows a warning, however it was selected | -"By name" means a plain selector list such as `--analyzers my-reach-analyzer`, or `+name` for a component that is off by default. A requirement that this version of Bomly does not know is never treated as met. +"By name" means a plain selector list such as `--analyzers my-reach-analyzer`, or `+name` for a component that is off by default. A requirement that this version of Bomly does not know is never treated as met. A component selected by name with such a requirement stops the command; a default component with one is skipped with a warning. The error names the component, the requirement, and what would meet it. This run selects an analyzer that needs a source tree while it reads an SBOM file: From 321b254b918d2c35857fc61e4febf3535e48459a Mon Sep 17 00:00:00 2001 From: Ahmed ElMallah Date: Sun, 25 Oct 2026 13:12:39 -0700 Subject: [PATCH 09/10] docs: apply the docs-criteria review to prerequisites and access disclosure - ADR-0050 returns as a retired stub: it was live on main, and numbers and filenames are kept. The index lists it under Retired (29 stubs). - ADR-0020 has one Revised line, a Context sentence on plugin trust, and an accurate account of when the access block is shown: at install and in plugins info; plugins enable shows it but asks for no confirmation. - PLUGINS.md lists every case that stops a run with exit 4 (as preflight's available() decides it), links the exit code and the SBOM glossary entry, says an omitted access list equals an empty one, and drops the circular "compare with what the plugin says". - EXIT_CODES.md gains the preflight case under exit 4. - The authoring guide links the prerequisites section inline and shows how a Go descriptor declares Requires. Refs bomly-dev/bomly-cli#535 Co-Authored-By: Claude Opus 5.5 --- ...y-configuration-requires-explicit-trust.md | 11 ++++++----- ...t-call-is-a-transaction-over-a-snapshot.md | 4 ++++ dev-docs/adr/README.md | 3 ++- docs/EXIT_CODES.md | 2 ++ docs/PLUGINS.md | 19 +++++++++++++------ docs/plugins/authoring.md | 10 ++++++++-- 6 files changed, 35 insertions(+), 14 deletions(-) create mode 100644 dev-docs/adr/0050-a-component-call-is-a-transaction-over-a-snapshot.md diff --git a/dev-docs/adr/0020-repository-configuration-requires-explicit-trust.md b/dev-docs/adr/0020-repository-configuration-requires-explicit-trust.md index f1ccbc56..0a2affe2 100644 --- a/dev-docs/adr/0020-repository-configuration-requires-explicit-trust.md +++ b/dev-docs/adr/0020-repository-configuration-requires-explicit-trust.md @@ -1,8 +1,7 @@ # ADR-0020: Repository configuration requires explicit trust; baselines are the one auto-discovered repository input - **Date:** 2026-07-25 -- **Revised:** 2026-10-19 (folds ADR-0003 and ADR-0019) -- **Revised:** 2026-10-25 (adds plugin access disclosure) +- **Revised:** 2026-10-25 (folds ADR-0003 and ADR-0019; adds plugin access disclosure) - **Status:** Accepted ## Context @@ -11,7 +10,8 @@ A configuration file can select a target, enable network enrichment, run package managers, load plugins and choose output paths. Loading one because it sits inside the checkout being scanned would let the checkout grant itself those permissions. Finding baselines also live in the repository, and -users expect them to apply without flags. +users expect them to apply without flags. A managed plugin runs with the +user's authority, so enabling one is the user's trust decision. ## Decision @@ -37,8 +37,9 @@ users expect them to apply without flags. baseline-specific stage or output model exists: a suppressed finding is an ordinary finding with `policy_status: suppressed`. - A managed plugin's manifest `access` block is the publisher's unverified - claim. Bomly shows it before the plugin is enabled and never enforces it. - An absent block means unknown and unrestricted, never "needs no access". + claim, shown at install (the plugin starts disabled) and in `plugins info`; + `plugins enable` shows it but asks for no confirmation. It is never + enforced. An absent block means unknown, never "needs no access". ## Rejected diff --git a/dev-docs/adr/0050-a-component-call-is-a-transaction-over-a-snapshot.md b/dev-docs/adr/0050-a-component-call-is-a-transaction-over-a-snapshot.md new file mode 100644 index 00000000..50bad39c --- /dev/null +++ b/dev-docs/adr/0050-a-component-call-is-a-transaction-over-a-snapshot.md @@ -0,0 +1,4 @@ +# ADR-0050: A component call is a transaction over a snapshot, within the command's lifetime + +- **Date:** 2026-10-25 +- **Status:** Retired 2026-10-25: implementation rationale, not a decision; see `dev-docs/ARCHITECTURE.md` (Scan Pipeline) diff --git a/dev-docs/adr/README.md b/dev-docs/adr/README.md index 444bb43d..4a3b10ba 100644 --- a/dev-docs/adr/README.md +++ b/dev-docs/adr/README.md @@ -2,7 +2,7 @@ An ADR records a choice Bomly made between viable alternatives, so the next person who proposes the other alternative finds the reasoning instead of -re-deriving it. The directory holds 21 live records and the stubs of 28 +re-deriving it. The directory holds 21 live records and the stubs of 29 retired ones; the full text of a retired record is in git history. ## When to write one @@ -111,3 +111,4 @@ Each file is a stub naming where the decision lives now. Cleaned up | ADR-0039 | [Both modules build on Go 1.27; untrusted JSON parses strictly](0039-both-modules-build-on-go-1-27.md) | Folded into ADR-0026 | | ADR-0045 | [The SDK owns the SBOM codec](0045-the-sdk-owns-the-sbom-codec.md) | Folded into ADR-0040 | | ADR-0046 | [The scan output is the SDK's scan record](0046-the-scan-output-is-the-sdk-scan-record.md) | Folded into ADR-0011 and ADR-0040 | +| ADR-0050 | [A component call is a transaction over a snapshot, within the command's lifetime](0050-a-component-call-is-a-transaction-over-a-snapshot.md) | Retired: implementation, see `dev-docs/ARCHITECTURE.md` (Scan Pipeline) | diff --git a/docs/EXIT_CODES.md b/docs/EXIT_CODES.md index 4979da28..3b43aaa2 100644 --- a/docs/EXIT_CODES.md +++ b/docs/EXIT_CODES.md @@ -44,6 +44,8 @@ Run with `-v` to see which project and detector failed. A flag, target, or config value is malformed. Examples: `--fail-on xyz` (the message lists the accepted values), `--format sarif` without `--audit`, `--audit` without `--enrich`, `--ref` without `--url`, or `-o spdx=` with an empty path. The error names the offending flag, and no partial output is produced. +A component you selected by name also exits `4` when the run can never meet a requirement it declares, for example an analyzer that needs a source tree while you scan an SBOM file. The error names the component, the requirement, and what would meet it. [Component prerequisites](PLUGINS.md#component-prerequisites) lists the cases. + ### `5`: nothing to evaluate No project was found at the target, so there was nothing to scan, diff, or audit. This differs from `3`. Exit `3` means Bomly found a project but could not turn it into a graph. Exit `5` means it found none. Typical causes: an `--ecosystems` or `--detectors` filter that matches nothing in the target (for example `--ecosystems maven` on an npm-only repository), or a directory, ref, or image with no supported manifests. The message lists the active filters and the candidates it skipped; see [Troubleshooting](TROUBLESHOOTING.md#nothing-to-evaluate-exit-5). diff --git a/docs/PLUGINS.md b/docs/PLUGINS.md index 4c4e8445..ec7714e8 100644 --- a/docs/PLUGINS.md +++ b/docs/PLUGINS.md @@ -110,7 +110,7 @@ A component can declare the inputs it needs before it can do useful work. Bomly | Requirement | Met when | | --- | --- | -| `source-tree-v1` | The target is a directory (`--path`) or a Git repository (`--url`), not an SBOM document or a container image | +| `source-tree-v1` | The target is a directory (`--path`) or a Git repository (`--url`), not an [SBOM](GLOSSARY.md) document or a container image | | `dependency-graph-v1` | Detection found at least one dependency. A detector cannot require it | | `vulnerability-records-v1` | At least one package carries a vulnerability record when analyzers and auditors run. This usually needs `--enrich` with a vulnerability [matcher](GLOSSARY.md) | @@ -118,11 +118,18 @@ What Bomly does with an unmet requirement depends on why the component is in the | Situation | Result | | --- | --- | -| You selected the component by name, and the run can never meet the requirement: the target is the wrong kind, or this version of Bomly does not know the requirement | The command stops with exit code 4 before any stage runs | +| You selected the component by name, and the run can never meet the requirement | The command stops with [exit code 4](EXIT_CODES.md#4-invalid-input) before any stage runs | | The component runs by default | Bomly skips it and shows a warning under that stage | | The requirement depends on what the scan found, such as no dependencies or no vulnerability records | Bomly skips it and shows a warning, however it was selected | -"By name" means a plain selector list such as `--analyzers my-reach-analyzer`, or `+name` for a component that is off by default. A requirement that this version of Bomly does not know is never treated as met. A component selected by name with such a requirement stops the command; a default component with one is skipped with a warning. +"By name" means a plain selector list such as `--analyzers my-reach-analyzer`, or `+name` for a component that is off by default. A run can never meet a requirement in these cases: + +- the component requires `source-tree-v1` and the target is an SBOM document or a container image; +- a detector requires `dependency-graph-v1` or `vulnerability-records-v1`, which only later stages produce; +- a matcher requires `vulnerability-records-v1`, which only analyzers and auditors can require; +- this version of Bomly does not know the requirement. + +A component selected by name in one of these cases stops the command. A component that runs by default is skipped with a warning instead. The error names the component, the requirement, and what would meet it. This run selects an analyzer that needs a source tree while it reads an SBOM file: @@ -168,7 +175,7 @@ Bomly cannot restrict a plugin's file or network access, stop it reading credent ### Declared access -A plugin's manifest can include an `access` block: the publisher's own statement of the files, network destinations, environment variables, and commands the plugin uses. Bomly shows it when you install the plugin, when you enable it (before the plugin is enabled), and in `bomly plugins info`, `verify`, and `doctor`. The `--json` forms of `list`, `info`, `verify`, and `doctor` carry it as `access`, with `accessDisclosure` set to `declared` or `unknown`. +A plugin's manifest can include an `access` block: the publisher's own statement of the files, network destinations, environment variables, and commands the plugin uses. Bomly shows it when you install the plugin, and in `bomly plugins info`, `verify`, and `doctor`. Plugins install disabled, so read it at install or with `bomly plugins info` before you enable the plugin. `bomly plugins enable` shows it again, but it does not ask for confirmation. The `--json` forms of `list`, `info`, `verify`, and `doctor` carry it as `access`, with `accessDisclosure` set to `declared` or `unknown`. This is how `bomly plugins enable` shows a declared block: @@ -186,7 +193,7 @@ Read the block as a description, not a limit: - Bomly does not check that the plugin behaves as declared, and it does not stop the plugin from doing more. A checksum proves the file is the one published, not that its behavior is safe. - A manifest without an `access` block shows `Declared access: unknown`. Treat that plugin as able to use everything your user account can. -- An `access` block with every list empty is the publisher's claim that the plugin needs none of that access. +- An `access` block with every list empty is the publisher's claim that the plugin needs none of that access. An omitted list means the same as an empty one, and Bomly shows it as `none declared`. - Bomly shows environment variable names only, never their values. - Bomly refuses to install a manifest whose `access` block is malformed or has an unknown key. The install error names the problem. @@ -194,7 +201,7 @@ Recommended practice: - Prefer `github:owner/repo@tag` installs from releases that publish `SHA256SUMS`. - Always pass `--checksum` for direct URL installs. -- Run `bomly plugins verify ` before you enable a plugin from an external source, and compare its declared access with what the plugin says it does. +- Run `bomly plugins verify ` before you enable a plugin from an external source, and compare its declared access with the plugin's own documentation. - Do not enable plugins you did not build or obtain from a source you control. [Security and trust boundaries](SECURITY.md) describes the wider trust model. diff --git a/docs/plugins/authoring.md b/docs/plugins/authoring.md index 452d71eb..1b34a3e0 100644 --- a/docs/plugins/authoring.md +++ b/docs/plugins/authoring.md @@ -57,9 +57,15 @@ A plugin's identity lives in three places: | The descriptor the binary returns | Component facts: name, display name, aliases, tags, supported ecosystems and package managers, optional `requires` list, role-specific behavior | You, in code | | Bomly's installed-plugin database | Checksum, enabled state, install path, and a snapshot of the descriptor | Bomly, at install time | -The descriptor's `requires` list names the inputs the component needs, such as `source-tree-v1`. Bomly checks it before the component runs. When every requirement is met, `Ready` and `Applicable` run as usual. When one is not, Bomly skips the component or stops the command; see the link below. +The descriptor's `requires` list names the inputs the component needs, such as `source-tree-v1`. Bomly checks it before the component runs. When every requirement is met, `Ready` and `Applicable` run as usual. When one is not, Bomly skips the component or stops the command, as [Component prerequisites](../PLUGINS.md#component-prerequisites) describes. -The manifest's `access` block discloses the files, network destinations, environment variables, and commands the plugin uses. Bomly shows it to users before they enable the plugin and does not enforce it. Leave a list empty only when the plugin needs none of that access. Without the block, users see the plugin's access as unknown. [Component prerequisites](../PLUGINS.md#component-prerequisites) and [Declared access](../PLUGINS.md#declared-access) describe both. +A Go descriptor declares the list with the SDK's constants: + +```go +plugin.AnalyzerDescriptor{Name: "my-reach-analyzer", Requires: plugin.Requirements{plugin.RequirementSourceTree}} +``` + +The manifest's `access` block discloses the files, network destinations, environment variables, and commands the plugin uses. Bomly shows it to users before they enable the plugin and does not enforce it. Leave a list empty only when the plugin needs none of that access. An omitted list means the same as an empty one, and users see it as `none declared`. Without the block, users see the plugin's access as unknown. [Declared access](../PLUGINS.md#declared-access) describes how users see it. The `access` block has five optional lists. Bomly sorts each list and removes duplicates when it reads the manifest: From 62b6a562130c85bb880ee28013c767b0f494031a Mon Sep 17 00:00:00 2001 From: Ahmed ElMallah Date: Sun, 25 Oct 2026 13:16:24 -0700 Subject: [PATCH 10/10] fix(engine): an SBOM beside source manifests leaves a source tree Discovery plans an SBOM found in a directory as its own subproject next to the directory's lockfiles, and any such subproject made preflight treat the whole target as an SBOM document, skipping or rejecting components that need source-tree-v1. A target is now an SBOM document only when every planned subproject is one, as with --sbom. Co-Authored-By: Claude Opus 5.5 --- internal/engine/preflight.go | 14 ++++++++------ internal/engine/preflight_test.go | 21 +++++++++++++++++++++ 2 files changed, 29 insertions(+), 6 deletions(-) diff --git a/internal/engine/preflight.go b/internal/engine/preflight.go index 69c90de2..b98ef1c5 100644 --- a/internal/engine/preflight.go +++ b/internal/engine/preflight.go @@ -123,13 +123,15 @@ type targetShape struct { } // describeTarget classifies the request's target. A filesystem path or a Git -// checkout is a source tree unless discovery planned it as an SBOM document; -// a container image, and a target whose kind is not recorded, is not. +// checkout is a source tree unless every planned subproject is an SBOM +// document, as with --sbom; an SBOM discovered beside source manifests +// leaves the directory a source tree. A container image, and a target whose +// kind is not recorded, is not one. func describeTarget(req PipelineRequest) targetShape { - for _, sub := range req.Subprojects { - if sub.PrimaryPackageManager() == model.PackageManagerSBOM { - return targetShape{description: "an SBOM document"} - } + if len(req.Subprojects) > 0 && !slices.ContainsFunc(req.Subprojects, func(sub plugin.Subproject) bool { + return sub.PrimaryPackageManager() != model.PackageManagerSBOM + }) { + return targetShape{description: "an SBOM document"} } switch req.ExecutionTarget.Kind { case plugin.ExecutionTargetFilesystem, plugin.ExecutionTargetGitRepository: diff --git a/internal/engine/preflight_test.go b/internal/engine/preflight_test.go index 1a23dc74..87a95961 100644 --- a/internal/engine/preflight_test.go +++ b/internal/engine/preflight_test.go @@ -552,3 +552,24 @@ func TestPreflight_ComponentAuditChecksEcosystemScopedAuditors(t *testing.T) { t.Fatalf("an explicitly selected ecosystem-scoped auditor that can never run must fail the plan, got %v", err) } } + +func TestPreflight_AnSBOMBesideSourceManifestsLeavesASourceTree(t *testing.T) { + // Discovery plans an SBOM found in a directory as its own subproject + // next to the directory's lockfiles. The directory is still a source + // tree; only a target whose every subproject is an SBOM is not. + graph := preflightGraph(t) + registry, req := preflightScenario(t, graph) + lockfile := req.Subprojects[0] + sbomTarget(registry, &req, graph) + sbom := req.Subprojects[0] + sbom.ExecutionTarget = ExecutionTarget{Kind: ExecutionTargetFilesystem, Location: "/repo/app.cdx.json"} + req.ExecutionTarget = ExecutionTarget{Kind: ExecutionTargetFilesystem, Location: "/repo"} + req.Subprojects = []Subproject{lockfile, sbom} + if shape := describeTarget(req); !shape.sourceTree { + t.Fatalf("a directory with lockfiles and an SBOM must stay a source tree, got %+v", shape) + } + req.Subprojects = []Subproject{sbom} + if shape := describeTarget(req); shape.sourceTree || shape.description != "an SBOM document" { + t.Fatalf("a target planned only as SBOM documents is not a source tree, got %+v", shape) + } +}