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 ¶
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 ¶
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 (*Matcher) Applicable ¶
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.
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 ¶
ProjectCheckDocRef points at the canonical documentation for a check.
type ProjectRepo ¶
ProjectRepo identifies the scored repository commit.
type ProjectVersion ¶
ProjectVersion identifies the Scorecard tool version that produced the run.