bomly-plugin-scorecard-matcher

module
v0.4.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 27, 2026 License: Apache-2.0

README

bomly-plugin-scorecard-matcher

OpenSSF Scorecard matcher for Bomly.

It attaches OpenSSF Scorecard project-posture data (aggregate score plus per-check results) to every package whose upstream source repository resolves to a github.com URL. Coverage is bounded by repo resolvability, not by ecosystem.

Already inside the Bomly CLI. This matcher ships embedded in the bomly binary as the built-in scorecard matcher — you do not need to install this plugin to use Scorecard enrichment. This repository is the matcher's home as a standalone module: the Bomly CLI consumes the same code in-process, and the plugin binary serves it to hosts that run matchers as managed subprocesses.

Identity

  • Plugin id / descriptor name: scorecard
  • Kind: matcher
  • Module path: github.com/bomly-dev/bomly-plugin-scorecard-matcher

Network behavior

This matcher performs network calls only during enrichment (bomly scan --enrich), never during audit-only runs:

  • https://api.scorecard.dev/projects/github.com/{owner}/{repo} — one fetch per unique resolved repository.

Responses are cached on disk (default ~/.bomly/cache/scorecard, 24h TTL); repositories the service has not scored are cached as a not-scored sentinel so they are not re-requested within the TTL. Transport failures degrade to warnings — a bad network never aborts the scan. Cache failures are non-fatal.

Access

bomly-plugin.json declares what the matcher touches, which Bomly shows when you install it and in bomly plugin info. It is a disclosure, not a sandbox.

Access Why
Reads and writes home The response cache, ~/.bomly/cache/scorecard by default
Network api.scorecard.dev The Scorecard API the matcher queries, the default api_base
Environment HOME, USERPROFILE os.UserHomeDir reads HOME (USERPROFILE on Windows) to locate the default cache directory

Resolving a package to its github.com repository reads only the package's own origins, PURL, resolved URL and metadata; it contacts no repository host. Setting cache_dir or api_base moves the cache or the API to a place you chose; the declaration describes the defaults. If Bomly cannot find your home directory, the matcher runs without a cache.

Configuration

Embedded execution is configured through the Bomly CLI's own scorecard settings. Managed execution reads a JSON block under plugins.matchers.scorecard:

Key Type Default Meaning
api_base string https://api.scorecard.dev Scorecard API base URL
cache_dir string ~/.bomly/cache/scorecard Response cache
cache_ttl duration string 24h Cache TTL
bypass_cache bool false Always fetch fresh results

Package-updates delta protocol

The matcher advertises package-updates-v1. When the host sets AcceptPackageUpdates, Match does not enrich the request registry and returns one delta per enriched package (PURL, Matched, and the scorecard). One nuance, documented in the descriptor: Package.MergeFrom fills Scorecard only when the target package has none, while the in-place path overwrites. This matcher is the sole producer of Package.Scorecard, so packages reach it un-scored and the two shapes agree in practice; the equivalence is pinned by TestMatchDeltaEquivalence.

Development

make test    # unit tests + SDK conformance suite
make build   # build bin/bomly-plugin-scorecard-matcher

License

Apache-2.0. See LICENSE and NOTICE.

Directories

Path Synopsis
cmd
bomly-plugin-scorecard-matcher command
Command bomly-plugin-scorecard-matcher serves the OpenSSF Scorecard matcher as a managed Bomly plugin over the HashiCorp go-plugin gRPC transport.
Command bomly-plugin-scorecard-matcher serves the OpenSSF Scorecard matcher as a managed Bomly plugin over the HashiCorp go-plugin gRPC transport.
Package scorecard implements an sdk.Matcher that enriches packages with upstream-project security-posture data from the OpenSSF Scorecard public API (api.scorecard.dev).
Package scorecard implements an sdk.Matcher that enriches packages with upstream-project security-posture data from the OpenSSF Scorecard public API (api.scorecard.dev).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL