checker

package
v5.0.0-rc1 Latest Latest
Warning

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

 Go to latest Published: Apr 12, 2024 License: Apache-2.0 Imports: 16 Imported by: 3

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 

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 

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 LogFinding 

func LogFinding(dl DetailLogger, f *finding.Finding, level DetailType)

LogFinding logs the given finding at the given level.

func NormalizeReason 

func NormalizeReason(reason string, score int) string

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

Types

type ArchivedStatus 

type ArchivedStatus struct {
	Status bool
}

ArchivedStatus defines 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 

type CIIBestPracticesData struct {
	Badge clients.BadgeLevel
}

CIIBestPracticesData contains data for CIIBestPractices check.

type CITestData 

type CITestData struct {
	CIInfo []RevisionCIInfo
}

type Changeset 

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

type Check 

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

	// Findings from the check's probes.
	Findings []finding.Finding
}

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. The score must be between MinResultScore and MaxResultScore. Callers who want InconclusiveResultScore must use CreateInconclusiveResult instead.

Passing an invalid score results in a runtime error result as if created by CreateRuntimeErrorResult.

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 

type CodeReviewData struct {
	DefaultBranchChangesets []Changeset
}

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

type ContributorsData 

type ContributorsData struct {
	Users []clients.User
}

ContributorsData represents contributor information.

type DangerousWorkflow 

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

DangerousWorkflow represents a dangerous workflow.

type DangerousWorkflowData 

type DangerousWorkflowData struct {
	Workflows    []DangerousWorkflow
	NumWorkflows int
}

DangerousWorkflowData contains raw results for dangerous workflow check.

type DangerousWorkflowType 

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 

type Dependency struct {
	// TODO: unique dependency name.
	// TODO: Job         *WorkflowJob
	Name        *string
	PinnedAt    *string
	Location    *File
	Msg         *string // Only for debug messages.
	Pinned      *bool
	Remediation *finding.Remediation
	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 

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 

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 ElementError 

type ElementError struct {
	Err      error
	Location finding.Location
}

ElementError allows us to identify the "element" that led to the given error. The "element" is the specific "code under analysis" that caused the error. It should describe what caused the error as precisely as possible.

For example, if a shell parsing error occurs while parsing a Dockerfile `RUN` block or a GitHub workflow's `run:` step, the "element" should point to the Dockerfile lines or workflow job step that caused the failure, not just the file path.

func (*ElementError) Error 

func (e *ElementError) Error() string

func (*ElementError) Unwrap 

func (e *ElementError) Unwrap() error

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 

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

Location generates location from a file.

type FuzzingData 

type FuzzingData struct {
	Fuzzers []Tool
}

FuzzingData represents different fuzzing done.

type License 

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 

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 

type LicenseData struct {
	LicenseFiles []LicenseFile
}

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

type LicenseFile 

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 *finding.Remediation // Remediation information, if any.
}

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

type MaintainedData 

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 

type MetadataData struct {
	Metadata map[string]string
}

type Package 

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.

type PackagingData 

type PackagingData struct {
	Packages []Package
}

PackagingData contains results for the Packaging check.

type PermissionLevel 

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 

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 

type PinningDependenciesData struct {
	Dependencies     []Dependency
	ProcessingErrors []ElementError // jobs or files with errors may have incomplete results
}

PinningDependenciesData represents pinned dependency data.

type ProportionalScoreWeighted 

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 {
	BinaryArtifactResults       BinaryArtifactData
	BranchProtectionResults     BranchProtectionsData
	CIIBestPracticesResults     CIIBestPracticesData
	CITestResults               CITestData
	CodeReviewResults           CodeReviewData
	ContributorsResults         ContributorsData
	DangerousWorkflowResults    DangerousWorkflowData
	DependencyUpdateToolResults DependencyUpdateToolData
	FuzzingResults              FuzzingData
	LicenseResults              LicenseData
	MaintainedResults           MaintainedData
	Metadata                    MetadataData
	PackagingResults            PackagingData
	PinningDependenciesResults  PinningDependenciesData
	SASTResults                 SASTData
	SecurityPolicyResults       SecurityPolicyData
	SignedReleasesResults       SignedReleasesData
	TokenPermissionsResults     TokenPermissionsData
	VulnerabilitiesResults      VulnerabilitiesData
	WebhookResults              WebhooksData
}

RawResults contains results before a policy is applied.

type RequestType 

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 

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

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

type ReviewPlatform 

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

type RevisionCIInfo 

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 

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 

func (r *Runner) SetCheckName(check string)

SetCheckName sets the check name.

func (*Runner) SetCheckRequest 

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

SetCheckRequest sets the check request.

func (*Runner) SetRepo 

func (r *Runner) SetRepo(repo string)

SetRepo sets the repository.

type SASTCommit 

type SASTCommit struct {
	CommittedDate          time.Time
	Message                string
	SHA                    string
	CheckRuns              []clients.CheckRun
	AssociatedMergeRequest clients.PullRequest
	Committer              clients.User
	Compliant              bool
}

type SASTData 

type SASTData struct {
	Workflows    []SASTWorkflow
	Commits      []SASTCommit
	NumWorkflows int
}

SASTData contains the raw results for the SAST check.

type SASTWorkflow 

type SASTWorkflow struct {
	Type SASTWorkflowType
	File File
}

SASTWorkflow represents a SAST workflow.

type SASTWorkflowType 

type SASTWorkflowType string

SASTWorkflowType represents a type of SAST workflow. 

const (
	// CodeQLWorkflow represents a workflow that runs CodeQL.
	CodeQLWorkflow SASTWorkflowType = "CodeQL"
	// SonarWorkflow represents a workflow that runs Sonar.
	SonarWorkflow SASTWorkflowType = "Sonar"
	// SnykWorkflow represents a workflow that runs Snyk.
	SnykWorkflow SASTWorkflowType = "Snyk"
	// PysaWorkflow represents a workflow that runs Pysa.
	PysaWorkflow SASTWorkflowType = "Pysa"
	// QodanaWorkflow represents a workflow that runs Qodana.
	QodanaWorkflow SASTWorkflowType = "Qodana"
)

type SecurityPolicyData 

type SecurityPolicyData struct {
	PolicyFiles []SecurityPolicyFile
}

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

type SecurityPolicyFile 

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

type SecurityPolicyInformation 

type SecurityPolicyInformation struct {
	InformationType  SecurityPolicyInformationType
	InformationValue SecurityPolicyValueType
}

type SecurityPolicyInformationType 

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

type SecurityPolicyValueType 

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 

type SignedReleasesData struct {
	Releases []clients.Release
}

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

type TokenPermission 

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 

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 

type VulnerabilitiesData struct {
	Vulnerabilities []clients.Vulnerability
}

VulnerabilitiesData contains the raw results for the Vulnerabilities check.

type WebhooksData 

type WebhooksData struct {
	Webhooks []clients.Webhook
}

WebhooksData contains the raw results for the Webhook check.

type WorkflowJob 

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.