Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion dev-docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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/<id>/<version>`.
7. Update `installed.json` atomically.
Expand Down
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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

Expand All @@ -35,16 +36,23 @@ 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

- CI that wants repository configuration states it once on the command line.
- 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`.
Original file line number Diff line number Diff line change
@@ -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)
4 changes: 2 additions & 2 deletions dev-docs/adr/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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) |
2 changes: 2 additions & 0 deletions docs/EXIT_CODES.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
63 changes: 62 additions & 1 deletion docs/PLUGINS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <plugin-id>` 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.<kind>.<name>`:
Expand Down Expand Up @@ -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 <id>` before you enable a plugin from an external source.
- Run `bomly plugins verify <id>` 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.
Expand Down
33 changes: 31 additions & 2 deletions docs/plugins/authoring.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading
Loading