diff --git a/dev-docs/ARCHITECTURE.md b/dev-docs/ARCHITECTURE.md index e63b0c81..a6bac864 100644 --- a/dev-docs/ARCHITECTURE.md +++ b/dev-docs/ARCHITECTURE.md @@ -92,6 +92,10 @@ 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. 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 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 +308,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/0020-repository-configuration-requires-explicit-trust.md b/dev-docs/adr/0020-repository-configuration-requires-explicit-trust.md index e10fb49f..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,7 +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 (folds ADR-0003 and ADR-0019; adds plugin access disclosure) - **Status:** Accepted ## Context @@ -10,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 @@ -35,11 +36,17 @@ 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, 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 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 +54,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 index 9442b798..50bad39c 100644 --- 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 @@ -1,54 +1,4 @@ # 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. +- **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 ea67294f..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 @@ -75,7 +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) | ## Retired @@ -112,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 42547f75..ec7714e8 100644 --- a/docs/PLUGINS.md +++ b/docs/PLUGINS.md @@ -104,6 +104,43 @@ 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. 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 | +| --- | --- | +| `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) | + +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 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 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: + +```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..`: @@ -136,11 +173,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, 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: + +```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. 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. + 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 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 1d7a23d5..1b34a3e0 100644 --- a/docs/plugins/authoring.md +++ b/docs/plugins/authoring.md @@ -53,10 +53,39 @@ 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. 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. + +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: + +| 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 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/plugin_access.go b/internal/cli/plugin_access.go new file mode 100644 index 00000000..604bd572 --- /dev/null +++ b/internal/cli/plugin_access.go @@ -0,0 +1,111 @@ +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 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{ + {"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..556a8611 --- /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") { + 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/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/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/pipeline.go b/internal/engine/pipeline.go index c5ca48f6..75f43754 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, stageData{}) + 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, 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 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, 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 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, stageData{graph: g, registry: 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, stageData{graph: g, registry: registry, ecosystem: auditReq.Ecosystem}) + 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..f5caa31c 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 } @@ -69,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 @@ -130,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.go b/internal/engine/preflight.go new file mode 100644 index 00000000..b98ef1c5 --- /dev/null +++ b/internal/engine/preflight.go @@ -0,0 +1,447 @@ +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. 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 + +// 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 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 { + 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: + 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, stageData{planning: true}) { + 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} +} + +// 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, data stageData) (*Pipeline, []PreflightIssue) { + facts := preflightFacts{ + stage: stage, + target: describeTarget(req), + matchStage: req.EnrichEnabled || req.MatchEnabled, + dependencyNodes: hasDependencyNode(data.graph), + vulnerabilityRecords: hasVulnerabilityRecord(data.registry), + } + candidates := p.stageCandidates(stage, req, data) + 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, data stageData) []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 + 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) + } + } + 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..87a95961 --- /dev/null +++ b/internal/engine/preflight_test.go @@ -0,0 +1,575 @@ +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, stageData{}) + 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) + } +} + +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 + // 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 { + 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.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"}} + _, 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) + } +} + +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) + } +} 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..c2584d07 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, @@ -829,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, @@ -902,23 +937,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 +1049,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 +1057,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 +1065,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/registry/view.go b/internal/registry/view.go new file mode 100644 index 00000000..780491bf --- /dev/null +++ b/internal/registry/view.go @@ -0,0 +1,63 @@ +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) +} + +// 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 +// 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) + } +} 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) + } +}