plugin

package
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 Imports: 19 Imported by: 0

Documentation

Overview

Package scorecard implements an sdk.Matcher that enriches packages with upstream-project security-posture data from the OpenSSF Scorecard public API (api.scorecard.dev). The matcher is opt-in via --matchers +scorecard and never modifies the dependency graph; it only annotates packages.

Index

Constants

View Source
const Name = "scorecard"

Name is the plugin's identity. It MUST equal the "id" field in bomly-plugin.json — Bomly refuses to load a plugin whose manifest id and runtime descriptor name disagree. It is also the descriptor name the Bomly CLI composition keys on when it embeds this matcher.

Variables

View Source
var ErrProjectNotScored = errors.New("scorecard: project not scored")

ErrProjectNotScored is returned by FetchProject when api.scorecard.dev has no run for the requested repository (HTTP 404). Callers should treat this as a benign skip, not a failure.

Functions

func Module

func Module() sdkplugin.Module

Module packages the matcher for both execution modes: Bomly can embed it in-process or serve it as a managed plugin subprocess (see cmd/bomly-plugin-scorecard-matcher).

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client fetches Scorecard runs from the public api.scorecard.dev endpoint.

func NewClient

func NewClient(config ClientConfig) *Client

NewClient creates a Scorecard HTTP client.

func (*Client) FetchProject

func (c *Client) FetchProject(ctx context.Context, repo string) (*Project, error)

FetchProject returns the Scorecard run for repo (e.g. "github.com/foo/bar"). Returns ErrProjectNotScored for HTTP 404 and a wrapped error for any other non-2xx status or transport failure.

type ClientConfig

type ClientConfig struct {
	APIBase            string
	Timeout            time.Duration
	UserAgent          string
	HTTPClient         *http.Client
	HTTPClientProvider *httpkit.ClientProvider
}

ClientConfig configures the Scorecard HTTP client.

func DefaultClientConfig

func DefaultClientConfig() ClientConfig

DefaultClientConfig returns a production-ready default config.

type Config

type Config struct {
	// APIBase overrides the api.scorecard.dev base URL. Defaults to
	// https://api.scorecard.dev.
	APIBase string
	// CacheDir overrides the on-disk cache directory. Defaults to
	// ~/.bomly/cache/scorecard.
	CacheDir string
	// CacheTTL is the time-to-live for cached responses. Defaults to 24h.
	CacheTTL time.Duration
	// BypassCache forces fresh fetches even when a cached response exists.
	BypassCache bool
	// ClientConfig overrides the HTTP client config. Useful for tests that
	// need to point at an httptest.Server or inject a custom HTTP client.
	// When non-nil, APIBase on the Config is ignored.
	ClientConfig *ClientConfig
	// Logger receives diagnostic messages. May be nil (no-op).
	Logger *zap.Logger
	// Stderr is used for user-visible warnings. May be nil.
	Stderr io.Writer
}

Config configures the Scorecard matcher.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns a production-ready Scorecard matcher config.

type Matcher

type Matcher struct {
	// contains filtered or unexported fields
}

Matcher attaches OpenSSF Scorecard runs to packages whose upstream source repository can be resolved to a github.com URL.

func New

func New(config Config) (*Matcher, error)

New creates a Scorecard matcher.

func (*Matcher) Applicable

func (m *Matcher) Applicable(_ context.Context, _ sdkplugin.MatchRequest) (bool, error)

Applicable reports whether this matcher applies to the given request.

func (*Matcher) Descriptor

func (m *Matcher) Descriptor() sdkplugin.MatcherDescriptor

Descriptor returns the matcher registration metadata.

func (*Matcher) Match

Match resolves Scorecard runs for every package whose upstream source repository can be identified as a github.com URL, then attaches the result to those packages. The matcher never returns an error from this method: transport failures degrade to per-repo warnings so a bad network does not abort the pipeline.

func (*Matcher) Ready

Ready reports whether this matcher can run. The Scorecard matcher only needs HTTP egress; no local binary or auth is required.

type Project

type Project struct {
	Date      string         `json:"date"`
	Repo      ProjectRepo    `json:"repo"`
	Scorecard ProjectVersion `json:"scorecard"`
	Score     float64        `json:"score"`
	Checks    []ProjectCheck `json:"checks"`
}

Project is the JSON wire shape returned by GET https://api.scorecard.dev/projects/{host}/{owner}/{repo}. Only the fields the matcher consumes are decoded; unknown fields are ignored.

type ProjectCheck

type ProjectCheck struct {
	Name          string             `json:"name"`
	Score         int                `json:"score"`
	Reason        string             `json:"reason"`
	Details       []string           `json:"details"`
	Documentation ProjectCheckDocRef `json:"documentation"`
}

ProjectCheck is one Scorecard check result.

type ProjectCheckDocRef

type ProjectCheckDocRef struct {
	Short string `json:"short"`
	URL   string `json:"url"`
}

ProjectCheckDocRef points at the canonical documentation for a check.

type ProjectRepo

type ProjectRepo struct {
	Name   string `json:"name"`
	Commit string `json:"commit"`
}

ProjectRepo identifies the scored repository commit.

type ProjectVersion

type ProjectVersion struct {
	Version string `json:"version"`
	Commit  string `json:"commit"`
}

ProjectVersion identifies the Scorecard tool version that produced the run.

Jump to

Keyboard shortcuts

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