checker

package
v4.13.0 Latest Latest
Warning

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

 Go to latest Published: Oct 5, 2023 License: Apache-2.0 Imports: 17 Imported by: 4

Documentation

Overview

Package checker includes structs and functions used for running a check.

Index

Constants

View Source 
const (
	// MaxResultScore is the best score that can be given by a check.
	MaxResultScore = 10
	// MinResultScore is the worst score that can be given by a check.
	MinResultScore = 0
	// InconclusiveResultScore is returned when no reliable information can be retrieved by a check.
	InconclusiveResultScore = -1

	// OffsetDefault is used if we can't determine the offset, for example when referencing a file but not a
	// specific location in the file.
	OffsetDefault = uint(1)
)

Variables

This section is empty.

Functions

func AggregateScores 

func AggregateScores(scores ...int) int

AggregateScores adds up all scores and normalizes the result. Each score contributes equally.

func AggregateScoresWithWeight 

func AggregateScoresWithWeight(scores map[int]int) int

AggregateScoresWithWeight adds up all scores and normalizes the result.

func CreateProportionalScore 

func CreateProportionalScore(success, total int) int

CreateProportionalScore creates a proportional score.

func CreateProportionalScoreWeighted added in v4.13.0 

func CreateProportionalScoreWeighted(scores ...ProportionalScoreWeighted) (int, error)

CreateProportionalScoreWeighted creates the proportional score between multiple successes over the total, but some proportions are worth more.

func GetClients added in v4.2.0 

func GetClients(ctx context.Context, repoURI, localURI string, logger *log.Logger) (
	clients.Repo,
	clients.RepoClient,
	clients.RepoClient,
	clients.CIIBestPracticesClient,
	clients.VulnerabilitiesClient,
	error,
)

GetClients returns a list of clients for running scorecard checks. TODO(repo): Pass a `http.RoundTripper` here.

func LogFindings added in v4.11.0 

func LogFindings(findings []finding.Finding, dl DetailLogger)

LogFindings logs the list of findings.

func NormalizeReason 

func NormalizeReason(reason string, score int) string

NormalizeReason - placeholder function if we want to update range of scores.

Types

type ArchivedStatus added in v4.2.0 

type ArchivedStatus struct {
	Status bool
}

ArchivedStatus definess the archived status.

type BinaryArtifactData 

type BinaryArtifactData struct {
	// Files contains a list of files.
	Files []File
}

BinaryArtifactData contains the raw results for the Binary-Artifact check.

type BranchProtectionsData 

type BranchProtectionsData struct {
	Branches        []clients.BranchRef
	CodeownersFiles []string
}

BranchProtectionsData contains the raw results for the Branch-Protection check.

type CIIBestPracticesData added in v4.3.0 

type CIIBestPracticesData struct {
	Badge clients.BadgeLevel
}

CIIBestPracticesData contains data foor CIIBestPractices check.

type CITestData added in v4.8.0 

type CITestData struct {
	CIInfo []RevisionCIInfo
}

type Changeset added in v4.7.0 

type Changeset struct {
	ReviewPlatform string
	RevisionID     string
	Commits        []clients.Commit
	Reviews        []clients.Review
	Author         clients.User
}

type Check added in v4.1.0 

type Check struct {
	Fn                    CheckFn
	SupportedRequestTypes []RequestType
}

Check defines a Scorecard check fn and its supported request types.

type CheckDetail 

type CheckDetail struct {
	Msg  LogMessage
	Type DetailType // Any of DetailWarn, DetailInfo, DetailDebug.
}

CheckDetail contains information for each detail.

type CheckFn 

type CheckFn func(*CheckRequest) CheckResult

CheckFn defined for convenience.

type CheckNameToFnMap 

type CheckNameToFnMap map[string]Check

CheckNameToFnMap defined here for convenience.

type CheckRequest 

type CheckRequest struct {
	Ctx                   context.Context
	RepoClient            clients.RepoClient
	CIIClient             clients.CIIBestPracticesClient
	OssFuzzRepo           clients.RepoClient
	Dlogger               DetailLogger
	Repo                  clients.Repo
	VulnerabilitiesClient clients.VulnerabilitiesClient
	// UPGRADEv6: return raw results instead of scores.
	RawResults    *RawResults
	RequiredTypes []RequestType
}

CheckRequest struct encapsulates all data to be passed into a CheckFn.

type CheckResult 

type CheckResult struct {
	Name    string
	Version int
	Error   error
	Score   int
	Reason  string
	Details []CheckDetail
	// Structured results.
	Rules []string // TODO(X): add support.
}

CheckResult captures result from a check run.

func CreateInconclusiveResult 

func CreateInconclusiveResult(name, reason string) CheckResult

CreateInconclusiveResult is used when the check runs without runtime errors, but we don't have enough evidence to set a score.

func CreateMaxScoreResult 

func CreateMaxScoreResult(name, reason string) CheckResult

CreateMaxScoreResult is used when the check runs without runtime errors and we can assign a maximum score to the result.

func CreateMinScoreResult 

func CreateMinScoreResult(name, reason string) CheckResult

CreateMinScoreResult is used when the check runs without runtime errors and we can assign a minimum score to the result.

func CreateProportionalScoreResult 

func CreateProportionalScoreResult(name, reason string, b, t int) CheckResult

CreateProportionalScoreResult is used when the check runs without runtime errors and we assign a proportional score. This may be used if a check contains multiple tests, and we want to assign a score proportional the number of tests that succeeded.

func CreateResultWithScore 

func CreateResultWithScore(name, reason string, score int) CheckResult

CreateResultWithScore is used when the check runs without runtime errors, and we want to assign a specific score.

func CreateRuntimeErrorResult 

func CreateRuntimeErrorResult(name string, e error) CheckResult

CreateRuntimeErrorResult is used when the check fails to run because of a runtime error.

type CodeReviewData added in v4.1.0 

type CodeReviewData struct {
	DefaultBranchChangesets []Changeset
}

CodeReviewData contains the raw results for the Code-Review check.

type ContributorsData added in v4.3.1 

type ContributorsData struct {
	Users []clients.User
}

ContributorsData represents contributor information.

type DangerousWorkflow added in v4.3.0 

type DangerousWorkflow struct {
	Job  *WorkflowJob
	Type DangerousWorkflowType
	File File
}

DangerousWorkflow represents a dangerous workflow.

type DangerousWorkflowData added in v4.2.0 

type DangerousWorkflowData struct {
	Workflows    []DangerousWorkflow
	NumWorkflows int
}

DangerousWorkflowData contains raw results for dangerous workflow check.

type DangerousWorkflowType added in v4.3.0 

type DangerousWorkflowType string

DangerousWorkflowType represents a type of dangerous workflow. 

const (
	// DangerousWorkflowScriptInjection represents a script injection.
	DangerousWorkflowScriptInjection DangerousWorkflowType = "scriptInjection"
	// DangerousWorkflowUntrustedCheckout represents an untrusted checkout.
	DangerousWorkflowUntrustedCheckout DangerousWorkflowType = "untrustedCheckout"
)

type Dependency added in v4.4.0 

type Dependency struct {
	// TODO: unique dependency name.
	// TODO: Job         *WorkflowJob
	Name     *string
	PinnedAt *string
	Location *File
	Msg      *string // Only for debug messages.
	Pinned   *bool
	Type     DependencyUseType
}

Dependency represents a dependency.

type DependencyUpdateToolData 

type DependencyUpdateToolData struct {
	// Tools contains a list of tools.
	Tools []Tool
}

DependencyUpdateToolData contains the raw results for the Dependency-Update-Tool check.

type DependencyUseType added in v4.4.0 

type DependencyUseType string

DependencyUseType represents a type of dependency use. 

const (
	// DependencyUseTypeGHAction is an action.
	DependencyUseTypeGHAction DependencyUseType = "GitHubAction"
	// DependencyUseTypeDockerfileContainerImage a container image used via FROM.
	DependencyUseTypeDockerfileContainerImage DependencyUseType = "containerImage"
	// DependencyUseTypeDownloadThenRun is a download followed by a run.
	DependencyUseTypeDownloadThenRun DependencyUseType = "downloadThenRun"
	// DependencyUseTypeGoCommand is a go command.
	DependencyUseTypeGoCommand DependencyUseType = "goCommand"
	// DependencyUseTypeChocoCommand is a choco command.
	DependencyUseTypeChocoCommand DependencyUseType = "chocoCommand"
	// DependencyUseTypeNpmCommand is an npm command.
	DependencyUseTypeNpmCommand DependencyUseType = "npmCommand"
	// DependencyUseTypePipCommand is a pip command.
	DependencyUseTypePipCommand DependencyUseType = "pipCommand"
	// DependencyUseTypeNugetCommand is a nuget command.
	DependencyUseTypeNugetCommand DependencyUseType = "nugetCommand"
)

type DetailLogger 

type DetailLogger interface {
	Info(msg *LogMessage)
	Warn(msg *LogMessage)
	Debug(msg *LogMessage)
	// Flush resets the logger state and returns collected logs.
	Flush() []CheckDetail
}

DetailLogger logs a CheckDetail struct.

func NewLogger added in v4.2.0 

func NewLogger() DetailLogger

NewLogger creates a new instance of `DetailLogger`.

type DetailType 

type DetailType int

DetailType is the type of details. 

const (
	// DetailInfo is info-level log.
	DetailInfo DetailType = iota
	// DetailWarn is warned log.
	DetailWarn
	// DetailDebug is debug log.
	DetailDebug
)

type File 

type File struct {
	Path      string
	Snippet   string           // Snippet of code
	Offset    uint             // Offset in the file of Path (line for source/text files).
	EndOffset uint             // End of offset in the file, e.g. if the command spans multiple lines.
	FileSize  uint             // Total size of file.
	Type      finding.FileType // Type of file.

}

File represents a file.

func (*File) Location added in v4.11.0 

func (f *File) Location() *finding.Location

Location generates location from a file.

type FuzzingData added in v4.3.1 

type FuzzingData struct {
	Fuzzers []Tool
}

FuzzingData represents different fuzzing done.

type License added in v4.9.0 

type License struct {
	Name        string                 // OSI standardized license name
	SpdxID      string                 // SPDX standardized identifier
	Attribution LicenseAttributionType // source of licensing information
	Approved    bool                   // FSF or OSI Approved License
}

license details.

type LicenseAttributionType added in v4.9.0 

type LicenseAttributionType string
const (
	// sources of license information used to assert repo's license.
	LicenseAttributionTypeOther      LicenseAttributionType = "other"
	LicenseAttributionTypeAPI        LicenseAttributionType = "repositoryAPI"
	LicenseAttributionTypeHeuristics LicenseAttributionType = "builtinHeuristics"
)

type LicenseData added in v4.2.0 

type LicenseData struct {
	LicenseFiles []LicenseFile
}

LicenseData contains the raw results for the License check. Some repos may have more than one license.

type LicenseFile added in v4.9.0 

type LicenseFile struct {
	LicenseInformation License
	File               File
}

one file contains one license.

type LogMessage 

type LogMessage struct {
	// Structured results.
	Finding *finding.Finding

	// Non-structured results.
	Text        string            // A short string explaining why the detail was recorded/logged.
	Path        string            // Fullpath to the file.
	Type        finding.FileType  // Type of file.
	Offset      uint              // Offset in the file of Path (line for source/text files).
	EndOffset   uint              // End of offset in the file, e.g. if the command spans multiple lines.
	Snippet     string            // Snippet of code
	Remediation *rule.Remediation // Remediation information, if any.
}

LogMessage is a structure that encapsulates detail's information. This allows updating the definition easily.

type MaintainedData added in v4.2.0 

type MaintainedData struct {
	CreatedAt            time.Time
	Issues               []clients.Issue
	DefaultBranchCommits []clients.Commit
	ArchivedStatus       ArchivedStatus
}

MaintainedData contains the raw results for the Maintained check.

type MetadataData added in v4.11.0 

type MetadataData struct {
	Metadata map[string]string
}

type Package added in v4.4.0 

type Package struct {
	// TODO: not supported yet. This needs to be unique across
	// ecosystems: purl, OSV, CPE, etc.
	Name *string
	Job  *WorkflowJob
	File *File
	// Note: Msg is populated only for debug messages.
	Msg  *string
	Runs []Run
}

Package represents a package. nolint

type PackagingData added in v4.4.0 

type PackagingData struct {
	Packages []Package
}

PackagingData contains results for the Packaging check.

type PermissionLevel added in v4.5.0 

type PermissionLevel string

PermissionLevel represents a permission type. 

const (
	// PermissionLevelUndeclared is an undeclared permission.
	PermissionLevelUndeclared PermissionLevel = "undeclared"
	// PermissionLevelWrite is a permission set to `write` for a permission we consider potentially dangerous.
	PermissionLevelWrite PermissionLevel = "write"
	// PermissionLevelRead is a permission set to `read`.
	PermissionLevelRead PermissionLevel = "read"
	// PermissionLevelNone is a permission set to `none`.
	PermissionLevelNone PermissionLevel = "none"
	// PermissionLevelUnknown is for other kinds of alerts, mostly to support debug messages.
	// TODO: remove it once we have implemented severity (#1874).
	PermissionLevelUnknown PermissionLevel = "unknown"
)

type PermissionLocation added in v4.5.0 

type PermissionLocation string

PermissionLocation represents a declaration type. 

const (
	// PermissionLocationTop is top-level workflow permission.
	PermissionLocationTop PermissionLocation = "topLevel"
	// PermissionLocationJob is job-level workflow permission.
	PermissionLocationJob PermissionLocation = "jobLevel"
)

type PinningDependenciesData added in v4.4.0 

type PinningDependenciesData struct {
	Dependencies []Dependency
}

PinningDependenciesData represents pinned dependency data.

type ProportionalScoreWeighted added in v4.13.0 

type ProportionalScoreWeighted struct {
	Success int
	Total   int
	Weight  int
}

ProportionalScoreWeighted is a structure that contains the fields to calculate weighted proportional scores.

type RawResults 

type RawResults struct {
	PackagingResults            PackagingData
	CIIBestPracticesResults     CIIBestPracticesData
	DangerousWorkflowResults    DangerousWorkflowData
	VulnerabilitiesResults      VulnerabilitiesData
	BinaryArtifactResults       BinaryArtifactData
	SecurityPolicyResults       SecurityPolicyData
	DependencyUpdateToolResults DependencyUpdateToolData
	BranchProtectionResults     BranchProtectionsData
	CodeReviewResults           CodeReviewData
	PinningDependenciesResults  PinningDependenciesData
	WebhookResults              WebhooksData
	ContributorsResults         ContributorsData
	MaintainedResults           MaintainedData
	SignedReleasesResults       SignedReleasesData
	FuzzingResults              FuzzingData
	LicenseResults              LicenseData
	TokenPermissionsResults     TokenPermissionsData
	CITestResults               CITestData
	Metadata                    MetadataData
}

RawResults contains results before a policy is applied. nolint

type RequestType added in v4.1.0 

type RequestType int

RequestType identifies special requirements/attributes that need to be supported by checks. 

const (
	// FileBased request types require checks to run solely on file-content.
	FileBased RequestType = iota
	// CommitBased request types require checks to run on non-HEAD commit content.
	CommitBased
)

func ListUnsupported added in v4.1.0 

func ListUnsupported(required, supported []RequestType) []RequestType

ListUnsupported returns []RequestType not in `supported` and are `required`.

type ReviewPlatform added in v4.7.0 

type ReviewPlatform = string
const (
	ReviewPlatformGitHub      ReviewPlatform = "GitHub"
	ReviewPlatformProw        ReviewPlatform = "Prow"
	ReviewPlatformGerrit      ReviewPlatform = "Gerrit"
	ReviewPlatformPhabricator ReviewPlatform = "Phabricator"
	ReviewPlatformPiper       ReviewPlatform = "Piper"
	ReviewPlatformUnknown     ReviewPlatform = "Unknown"
)

type RevisionCIInfo added in v4.8.0 

type RevisionCIInfo struct {
	HeadSHA           string
	CheckRuns         []clients.CheckRun
	Statuses          []clients.Status
	PullRequestNumber int
}

type Run 

type Run struct {
	URL string
}

Run represents a run.

type Runner 

type Runner struct {
	CheckName    string
	Repo         string
	CheckRequest CheckRequest
}

Runner runs a check with retries.

func NewRunner added in v4.2.0 

func NewRunner(checkName, repo string, checkReq *CheckRequest) *Runner

NewRunner creates a new instance of `Runner`.

func (*Runner) Run 

func (r *Runner) Run(ctx context.Context, c Check) CheckResult

Run runs a given check.

func (*Runner) SetCheckName added in v4.2.0 

func (r *Runner) SetCheckName(check string)

SetCheckName sets the check name.

func (*Runner) SetCheckRequest added in v4.2.0 

func (r *Runner) SetCheckRequest(checkReq *CheckRequest)

SetCheckRequest sets the check request.

func (*Runner) SetRepo added in v4.2.0 

func (r *Runner) SetRepo(repo string)

SetRepo sets the repository.

type SecurityPolicyData 

type SecurityPolicyData struct {
	PolicyFiles []SecurityPolicyFile
}

SecurityPolicyData contains the raw results for the Security-Policy check.

type SecurityPolicyFile added in v4.9.0 

type SecurityPolicyFile struct {
	// security policy information found in repo or org
	Information []SecurityPolicyInformation
	// file that contains the security policy information
	File File
}

type SecurityPolicyInformation added in v4.9.0 

type SecurityPolicyInformation struct {
	InformationType  SecurityPolicyInformationType
	InformationValue SecurityPolicyValueType
}

type SecurityPolicyInformationType added in v4.9.0 

type SecurityPolicyInformationType string
const (
	// forms of security policy hints being evaluated.
	SecurityPolicyInformationTypeEmail SecurityPolicyInformationType = "emailAddress"
	SecurityPolicyInformationTypeLink  SecurityPolicyInformationType = "httpLink"
	SecurityPolicyInformationTypeText  SecurityPolicyInformationType = "vulnDisclosureText"
)

type SecurityPolicyValueType added in v4.9.0 

type SecurityPolicyValueType struct {
	Match      string // Snippet of match
	LineNumber uint   // Line number in policy file of match
	Offset     uint   // Offset in the line of the match
}

type SignedReleasesData added in v4.2.0 

type SignedReleasesData struct {
	Releases []clients.Release
}

SignedReleasesData contains the raw results for the Signed-Releases check.

type TokenPermission added in v4.5.0 

type TokenPermission struct {
	Job          *WorkflowJob
	LocationType *PermissionLocation
	Name         *string
	Value        *string
	File         *File
	Msg          *string
	Type         PermissionLevel
}

TokenPermission defines a token permission result.

type TokenPermissionsData added in v4.5.0 

type TokenPermissionsData struct {
	TokenPermissions []TokenPermission
	NumTokens        int
}

TokenPermissionsData represents data about a permission failure.

type Tool 

type Tool struct {
	URL   *string
	Desc  *string
	Files []File
	Name  string
	// Runs of the tool.
	Runs []Run
	// Issues created by the tool.
	Issues []clients.Issue
	// Merge requests created by the tool.
	MergeRequests []clients.PullRequest
}

Tool represents a tool.

type VulnerabilitiesData added in v4.1.0 

type VulnerabilitiesData struct {
	Vulnerabilities []clients.Vulnerability
}

VulnerabilitiesData contains the raw results for the Vulnerabilities check.

type WebhooksData added in v4.2.0 

type WebhooksData struct {
	Webhooks []clients.Webhook
}

WebhooksData contains the raw results for the Webhook check.

type WorkflowJob added in v4.2.0 

type WorkflowJob struct {
	Name *string
	ID   *string
}

WorkflowJob represents a workflow job.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.