checker

Documentation

Overview

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

Index

• Constants
• func AggregateScores(scores ...int) int
• func AggregateScoresWithWeight(scores map[int]int) int
• func CreateProportionalScore(success, total int) int
• func NormalizeReason(reason string, score int) string
• type BinaryArtifactData
• type BranchProtectionData
• type BranchProtectionsData
• type CheckDetail
• type CheckFn
• type CheckNameToFnMap
• type CheckRequest
• type CheckResult
  • func CreateInconclusiveResult(name, reason string) CheckResult
  • func CreateMaxScoreResult(name, reason string) CheckResult
  • func CreateMinScoreResult(name, reason string) CheckResult
  • func CreateProportionalScoreResult(name, reason string, b, t int) CheckResult
  • func CreateResultWithScore(name, reason string, score int) CheckResult
  • func CreateRuntimeErrorResult(name string, e error) CheckResult
• type DependencyUpdateToolData
• type DetailLogger
• type DetailType
• type File
• type FileType
• type Issue
• type LogMessage
• type MergeRequest
• type RawResults
• type Run
• type Runner
  • func (r *Runner) Run(ctx context.Context, f CheckFn) CheckResult
• type SecurityPolicyData
• type Tool

Constants

const (
	// MaxResultConfidence implies full certainty about a check result.
	// TODO(#1393): remove after deprecation.
	MaxResultConfidence = 10
	// HalfResultConfidence signifies uncertainty about a check's score.
	// TODO(#1393): remove after deprecation.
	HalfResultConfidence = 5
	// MinResultConfidence signifies no confidence in the check result.
	// TODO(#1393): remove after deprecation.
	MinResultConfidence = 0

	// 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)
)

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 NormalizeReason

func NormalizeReason(reason string, score int) string

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

Types

type BinaryArtifactData

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

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

type BranchProtectionData

type BranchProtectionData struct {
	Protected                           *bool
	AllowsDeletions                     *bool
	AllowsForcePushes                   *bool
	RequiresCodeOwnerReviews            *bool
	RequiresLinearHistory               *bool
	DismissesStaleReviews               *bool
	EnforcesAdmins                      *bool
	RequiresStatusChecks                *bool
	RequiresUpToDateBranchBeforeMerging *bool
	RequiredApprovingReviewCount        *int
	// StatusCheckContexts is always available, so
	// we don't use a pointer.
	StatusCheckContexts []string
	Name                string
}

BranchProtectionData contains the raw results for one branch.

type BranchProtectionsData

type BranchProtectionsData struct {
	Branches []BranchProtectionData
}

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

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]CheckFn

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
}

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

type CheckResult

type CheckResult struct {
	// TODO(#1393): Remove old structure after deprecation.
	Error      error `json:"-"`
	Name       string
	Details    []string
	Confidence int
	Pass       bool

	// UPGRADEv2: New structure. Omitting unchanged Name field
	// for simplicity.
	Version  int           `json:"-"` // Default value of 0 indicates old structure.
	Error2   error         `json:"-"` // Runtime error indicate a filure to run the check.
	Details2 []CheckDetail `json:"-"` // Details of tests and sub-checks
	Score    int           `json:"-"` // {[-1,0...10], -1 = Inconclusive}
	Reason   string        `json:"-"` // A sentence describing the check result (score, etc)
}

CheckResult captures result from a check run. nolint:govet

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 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 DependencyUpdateToolData

type DependencyUpdateToolData struct {
	// Tools contains a list of tools.
	// Note: we only populate one entry at most.
	Tools []Tool
}

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

type DetailLogger

type DetailLogger interface {
	Info(desc string, args ...interface{})
	Warn(desc string, args ...interface{})
	Debug(desc string, args ...interface{})

	// Functions to use for moving to SARIF format.
	// UPGRADEv3: to rename.
	Info3(msg *LogMessage)
	Warn3(msg *LogMessage)
	Debug3(msg *LogMessage)
}

DetailLogger logs a CheckDetail struct.

type DetailType

type DetailType int

DetailType is the type of details.

const (
	// DetailInfo is info-level log.
	DetailInfo DetailType = iota
	// DetailWarn is warn 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).
	Type    FileType // Type of file.

}

File represents a file.

type FileType

type FileType int

FileType is the type of a file.

const (
	// FileTypeNone is a default, not defined.
	// FileTypeNone must be `0`.
	FileTypeNone FileType = iota
	// FileTypeSource is for source code files.
	FileTypeSource
	// FileTypeBinary is for binary files.
	FileTypeBinary
	// FileTypeText is for text files.
	FileTypeText
	// FileTypeURL for URLs.
	FileTypeURL
)

type Issue

type Issue struct {
	URL string
}

Issue represents an issue.

type LogMessage

type LogMessage struct {
	Text      string   // A short string explaining why the detail was recorded/logged.
	Path      string   // Fullpath to the file.
	Type      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
	// UPGRADEv3: to remove.
	Version int // `3` to indicate the detail was logged using new structure.
}

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

type MergeRequest

type MergeRequest struct {
	URL string
}

MergeRequest represents a merge request.

type RawResults

type RawResults struct {
	BinaryArtifactResults       BinaryArtifactData
	SecurityPolicyResults       SecurityPolicyData
	DependencyUpdateToolResults DependencyUpdateToolData
	BranchProtectionResults     BranchProtectionsData
}

RawResults contains results before a policy is applied.

type Run

type Run struct {
	URL string
}

Run represents a run.

type Runner

type Runner struct {
	CheckRequest CheckRequest
	CheckName    string
	Repo         string
}

Runner runs a check with retries.

func (*Runner) Run

func (r *Runner) Run(ctx context.Context, f CheckFn) CheckResult

Run runs a given check.

type SecurityPolicyData

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

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

type Tool

type Tool struct {
	// Runs of the tool.
	Runs []Run
	// Issues created by the tool.
	Issues []Issue
	// Merges requests created by the tool.
	MergeRequests []MergeRequest
	Name          string
	URL           string
	Desc          string
	ConfigFiles   []File
}

Tool represents a tool.