scorecard

package
v0.14.2 Latest Latest
Warning

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

Go to latest
Published: Jun 16, 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

This section is empty.

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

This section is empty.

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 *sdk.HTTPClientProvider
}

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, _ sdk.MatchRequest) (bool, error)

Applicable reports whether this matcher applies to the given request.

func (*Matcher) Descriptor

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

Descriptor returns the matcher registration metadata.

func (*Matcher) Match

func (m *Matcher) Match(ctx context.Context, req sdk.MatchRequest) (sdk.MatchResult, error)

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

func (m *Matcher) Ready() bool

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