Documentation
¶
Index ¶
- Variables
- func Loader(config *config.Config) (payload any, err error)
- type BinaryAnalysis
- type ClientMock
- type GitHubRepositoryMetadata
- func (r *GitHubRepositoryMetadata) DefaultBranchRequiresPRReviews() *bool
- func (r *GitHubRepositoryMetadata) HasBranchRules() bool
- func (r *GitHubRepositoryMetadata) Homepage() string
- func (r *GitHubRepositoryMetadata) IsActive() bool
- func (r *GitHubRepositoryMetadata) IsDefaultBranchProtected() *bool
- func (r *GitHubRepositoryMetadata) IsDefaultBranchProtectedFromDeletion() *bool
- func (r *GitHubRepositoryMetadata) IsPublic() bool
- func (r *GitHubRepositoryMetadata) OrganizationBlogURL() *string
- func (r *GitHubRepositoryMetadata) RequiredStatusCheckContexts() []string
- func (r *GitHubRepositoryMetadata) RulesetsObserved() bool
- func (r *GitHubRepositoryMetadata) ViewerCanAdminister() bool
- type GraphqlRepoData
- type GraphqlRepoTree
- type GraphqlWorkflowFiles
- type HttpClient
- type Payload
- type PrivateVulnReporting
- type ReleaseAsset
- type ReleaseData
- type RepoContent
- type RepoSecurityPosture
- func (rsp *RepoSecurityPosture) DefinesPolicyForHandlingSecrets() bool
- func (rsp *RepoSecurityPosture) InsightsDeclaresSecretScanning() bool
- func (rsp *RepoSecurityPosture) PreventsPushingSecrets() bool
- func (rsp *RepoSecurityPosture) ScansForSecrets() bool
- func (rsp *RepoSecurityPosture) SecretScanningObservable() bool
- type RepositoryMetadata
- type RestData
- func (r *RestData) DependencyToolingConfig() string
- func (r *RestData) FindFile(names ...string) string
- func (r *RestData) FindFileInDirs(dirs, names []string) string
- func (r *RestData) GetFileContent(path string) (content *github.RepositoryContent, err error)
- func (r *RestData) HasBuildInstructions() bool
- func (r *RestData) HasSupportMarkdown() bool
- func (r *RestData) IsCodeRepo() (bool, error)
- func (r *RestData) MakeApiCall(endpoint string, isGithub bool) (body []byte, err error)
- func (r *RestData) Setup() error
- type SecurityPolicy
- type SecurityPosture
- type WorkflowBlob
- type WorkflowBlobObject
- type WorkflowFile
- type WorkflowPermissions
- type WorkflowTreeEntry
Constants ¶
This section is empty.
Variables ¶
var APIBase = "https://api.github.com"
Functions ¶
Types ¶
type BinaryAnalysis ¶ added in v0.27.0
type BinaryAnalysis struct {
Suspected []string // OSPS-QA-05.01: suspected executable binary artifacts
Unreviewable []string // OSPS-QA-05.02: unreviewable binary artifacts
Err error
}
BinaryAnalysis holds information about binaries found in the repo
type ClientMock ¶
type GitHubRepositoryMetadata ¶
type GitHubRepositoryMetadata struct {
Releases []ReleaseData
// contains filtered or unexported fields
}
func (*GitHubRepositoryMetadata) DefaultBranchRequiresPRReviews ¶ added in v0.19.0
func (r *GitHubRepositoryMetadata) DefaultBranchRequiresPRReviews() *bool
func (*GitHubRepositoryMetadata) HasBranchRules ¶ added in v0.27.0
func (r *GitHubRepositoryMetadata) HasBranchRules() bool
HasBranchRules reports whether any ruleset at all applies to the default branch, which determines whether rulesets or branch protection are treated as the authoritative source for status check requirements.
func (*GitHubRepositoryMetadata) Homepage ¶ added in v0.28.0
func (r *GitHubRepositoryMetadata) Homepage() string
Homepage returns the repository's configured homepage URL, or "" when unset. It is observable without Security Insights and used as a fallback link to evaluate for HTTPS. GetHomepage is nil-safe on a missing repository.
func (*GitHubRepositoryMetadata) IsActive ¶
func (r *GitHubRepositoryMetadata) IsActive() bool
func (*GitHubRepositoryMetadata) IsDefaultBranchProtected ¶ added in v0.19.0
func (r *GitHubRepositoryMetadata) IsDefaultBranchProtected() *bool
func (*GitHubRepositoryMetadata) IsDefaultBranchProtectedFromDeletion ¶ added in v0.19.0
func (r *GitHubRepositoryMetadata) IsDefaultBranchProtectedFromDeletion() *bool
func (*GitHubRepositoryMetadata) IsPublic ¶
func (r *GitHubRepositoryMetadata) IsPublic() bool
func (*GitHubRepositoryMetadata) OrganizationBlogURL ¶
func (r *GitHubRepositoryMetadata) OrganizationBlogURL() *string
func (*GitHubRepositoryMetadata) RequiredStatusCheckContexts ¶ added in v0.27.0
func (r *GitHubRepositoryMetadata) RequiredStatusCheckContexts() []string
RequiredStatusCheckContexts returns the names of the status checks that the default branch's rulesets mark as required.
func (*GitHubRepositoryMetadata) RulesetsObserved ¶ added in v0.27.0
func (r *GitHubRepositoryMetadata) RulesetsObserved() bool
RulesetsObserved reports whether the ruleset lookup for the default branch actually completed. The rulesets REST API is publicly readable, so a nil value means the fetch failed rather than that no rulesets exist — this lets callers tell "observed, none configured" from "never observed".
func (*GitHubRepositoryMetadata) ViewerCanAdminister ¶ added in v0.27.0
func (r *GitHubRepositoryMetadata) ViewerCanAdminister() bool
ViewerCanAdminister reports whether the scanning token holds admin on the repository. GitHub exposes classic branch protection (the GraphQL BranchProtectionRule and RefUpdateRule objects) only to admins; for any other token they come back as zero values indistinguishable from "no protection". Callers gate on this to tell an observed absence of protection apart from an invisible one.
type GraphqlRepoData ¶
type GraphqlRepoData struct {
Repository struct {
Name string
HasDiscussionsEnabled bool
HasIssuesEnabled bool
IsSecurityPolicyEnabled bool
Object struct {
Tree struct {
Entries []struct {
Name string
Type string // "blob" for files, "tree" for directories
Path string
}
} `graphql:"... on Tree"`
} `graphql:"object(expression: \"HEAD:\")"`
DefaultBranchRef struct {
Name string
RefUpdateRule struct {
AllowsDeletions bool
AllowsForcePushes bool
RequiredApprovingReviewCount int
}
BranchProtectionRule struct {
RestrictsPushes bool // This didn't give an accurate result
RequiresApprovingReviews bool // This gave an accurate result
RequiresCommitSignatures bool
RequiresStatusChecks bool
RequireLastPushApproval bool
RequiredStatusCheckContexts []string
}
Target struct {
OID string `graphql:"oid"` // Latest commit SHA
Commit struct {
Status struct {
State string // Overall commit status
Contexts []struct {
Context string
Description string
State string
TargetURL string `graphql:"targetUrl"`
}
} `graphql:"status"` // Classic status API
AssociatedPullRequests struct {
Nodes []struct {
StatusCheckRollup struct {
Commit struct {
CheckSuites struct {
Nodes []struct {
CheckRuns struct {
Nodes []struct {
Name string `graphql:"name"`
}
} `graphql:"checkRuns(first: 25)"`
}
} `graphql:"checkSuites(first: 25)"`
}
}
}
} `graphql:"associatedPullRequests(last: 1)"`
} `graphql:"... on Commit"`
} `graphql:"target"`
}
LicenseInfo struct {
Name string
SpdxId string
Url string
}
LatestRelease struct {
Description string
}
ContributingGuidelines struct {
Body string
}
Releases struct {
Nodes []struct {
TagName string
Name string
Assets struct {
Nodes []struct {
Name string
ContentType string
}
} `graphql:"releaseAssets(first: 100)"`
}
} `graphql:"releases(first: 1, orderBy: {field: CREATED_AT, direction: DESC})"`
// Selected here rather than in its own query: it targets the same
// repository node, so it costs nothing extra to fetch alongside.
DependencyGraphManifests struct {
TotalCount int
}
} `graphql:"repository(owner: $owner, name: $name)"`
}
GraphqlRepoData is used in a query to get general repository information
type GraphqlRepoTree ¶
type GraphqlRepoTree struct {
Repository struct {
Object struct {
Tree struct {
Entries []struct {
Name string
Type string
Path string
Mode int
Object *struct {
Blob struct {
IsBinary *bool
IsTruncated bool
} `graphql:"... on Blob"`
Tree struct {
Entries []struct {
Name string
Type string
Path string
Mode int
Object *struct {
Blob struct {
IsBinary *bool
IsTruncated bool
} `graphql:"... on Blob"`
Tree struct {
Entries []struct {
Name string
Type string
Path string
Mode int
Object *struct {
Blob struct {
IsBinary *bool
IsTruncated bool
} `graphql:"... on Blob"`
} `graphql:"object"`
}
} `graphql:"... on Tree"`
} `graphql:"object"`
}
} `graphql:"... on Tree"`
} `graphql:"object"`
}
} `graphql:"... on Tree"`
} `graphql:"object(expression: $branch)"`
} `graphql:"repository(owner: $owner, name: $name)"`
}
type GraphqlWorkflowFiles ¶ added in v0.27.0
type GraphqlWorkflowFiles struct {
Repository struct {
Object struct {
Tree struct {
Entries []WorkflowTreeEntry
} `graphql:"... on Tree"`
} `graphql:"object(expression: $expression)"`
} `graphql:"repository(owner: $owner, name: $name)"`
}
GraphqlWorkflowFiles is the query for a single directory's entries, selecting each entry's name, path, and full text in one round trip.
type Payload ¶
type Payload struct {
*GraphqlRepoData
*RestData
*pluginkit.APICallCounter // Enable Privateer benchmarking for API calls
Evidence *gemara.EvidenceCollector
Config *config.Config
RepositoryMetadata RepositoryMetadata
DependencyManifestsCount int
IsCodeRepo bool
SecurityPosture SecurityPosture
Binaries BinaryAnalysis
// contains filtered or unexported fields
}
func NewPayloadWithHTTPMock ¶
func NewPayloadWithRepoContents ¶ added in v0.28.0
func NewPayloadWithRepoContents(base Payload, root []*github.RepositoryContent, subContents map[string][]*github.RepositoryContent) Payload
NewPayloadWithRepoContents builds a Payload whose RestData is backed by the given root and subdirectory listings, so that other packages' tests can exercise contents-based fallbacks (checkFile, FindFile, FindFileInDirs) without a live GitHub client. subContents maps a directory path such as ".github" or "docs" to its file listing.
func (Payload) AddEvidence ¶ added in v0.28.0
AddEvidence, GetEvidence, and ClearEvidence implement gemara.HasEvidence. Nil-safe: a payload without a collector silently drops evidence.
func (Payload) ClearEvidence ¶ added in v0.28.0
func (p Payload) ClearEvidence()
func (Payload) GetEvidence ¶ added in v0.28.0
func (*Payload) GetWorkflowFiles ¶ added in v0.27.0
func (p *Payload) GetWorkflowFiles() ([]WorkflowFile, error)
GetWorkflowFiles returns the decoded contents of every file in .github/workflows using a single GraphQL call, cached for reuse across the several build/release checks that inspect workflows.
type PrivateVulnReporting ¶ added in v0.28.0
PrivateVulnReporting captures the repository's private-vulnerability-reporting setting as observed through the GitHub REST API. GitHub only answers this for public repositories and returns 404 otherwise, so Known distinguishes an observed value from "could not observe": an error or missing endpoint leaves Known false rather than reporting a confident Enabled=false. Steps rely on that distinction to choose NeedsReview over Failed when the signal is absent.
type ReleaseAsset ¶
type ReleaseData ¶
type ReleaseData struct {
Id int `json:"id"`
Name string `json:"name"`
TagName string `json:"tag_name"`
URL string `json:"url"`
Assets []ReleaseAsset `json:"assets"`
}
type RepoContent ¶
type RepoContent struct {
Content []*github.RepositoryContent
SubContent map[string]RepoContent
}
type RepoSecurityPosture ¶
type RepoSecurityPosture struct {
// contains filtered or unexported fields
}
func (*RepoSecurityPosture) DefinesPolicyForHandlingSecrets ¶
func (rsp *RepoSecurityPosture) DefinesPolicyForHandlingSecrets() bool
func (*RepoSecurityPosture) InsightsDeclaresSecretScanning ¶ added in v0.28.0
func (rsp *RepoSecurityPosture) InsightsDeclaresSecretScanning() bool
func (*RepoSecurityPosture) PreventsPushingSecrets ¶
func (rsp *RepoSecurityPosture) PreventsPushingSecrets() bool
func (*RepoSecurityPosture) ScansForSecrets ¶
func (rsp *RepoSecurityPosture) ScansForSecrets() bool
func (*RepoSecurityPosture) SecretScanningObservable ¶ added in v0.28.0
func (rsp *RepoSecurityPosture) SecretScanningObservable() bool
type RepositoryMetadata ¶
type RepositoryMetadata interface {
IsActive() bool
IsPublic() bool
Homepage() string
OrganizationBlogURL() *string
IsDefaultBranchProtected() *bool
DefaultBranchRequiresPRReviews() *bool
IsDefaultBranchProtectedFromDeletion() *bool
HasBranchRules() bool
RequiredStatusCheckContexts() []string
RulesetsObserved() bool
ViewerCanAdminister() bool
}
type RestData ¶
type RestData struct {
Config *config.Config
WorkflowsEnabled bool
WorkflowPermissions WorkflowPermissions
// WorkflowPermissionsObserved is true only when both admin-only Actions
// endpoints were fetched and parsed successfully. When false, WorkflowsEnabled
// and WorkflowPermissions are unset defaults rather than observed values, and
// callers must not read "Actions disabled" or "write default" into them.
WorkflowPermissionsObserved bool
Insights si.SecurityInsights
InsightsError bool
PrivateVulnReporting PrivateVulnReporting
SecurityPolicy SecurityPolicy
Releases []ReleaseData
HttpClient HttpClient `json:"-" yaml:"-"`
// contains filtered or unexported fields
}
func NewRestDataWithContents ¶ added in v0.28.0
func NewRestDataWithContents(contents RepoContent) *RestData
NewRestDataWithContents returns a RestData seeded with canned repository contents so file-presence checks can be exercised without a GitHub client. Pre-populating SubContent (e.g. for ".github") lets checkFile answer from the cache instead of making an API call. Security Insights is initialized to its empty-but-non-nil shape, matching the state Setup leaves it in.
func NewRestDataWithFailingClient ¶ added in v0.28.0
NewRestDataWithFailingClient returns a RestData whose GitHub REST client always fails with err, letting other packages' tests exercise transient fetch-error paths (e.g. GetFileContent) without a live GitHub API.
func (*RestData) DependencyToolingConfig ¶ added in v0.28.0
DependencyToolingConfig returns the path to the first automated dependency-update tool config found in the repository root or .github directory, or "" when none is present. checkFile probes .github case-insensitively, which is where Dependabot configs live.
func (*RestData) FindFile ¶ added in v0.27.0
FindFile returns the repository path of the first of the given filenames found in the repository root or .github directory, matched case-insensitively. It reuses the REST contents fetched during Setup, so once .github has been probed it costs no additional API call. Returns "" when none of the names is present.
It exists so evaluation steps in other packages can run deterministic filesystem fallbacks without reaching into RestData's unexported checkFile.
func (*RestData) FindFileInDirs ¶ added in v0.28.0
FindFileInDirs returns the repository path of the first of the given filenames found in any of the given directories, matched case-insensitively. The empty string denotes the repository root. Directories absent from the cached root listing are skipped rather than fetched, and the search reuses the REST contents gathered during Setup. Returns "" when none of the names is present.
It exists so evaluation steps in other packages can run deterministic filesystem fallbacks (root, .github, docs) without reaching into RestData's unexported helpers.
func (*RestData) GetFileContent ¶
func (r *RestData) GetFileContent(path string) (content *github.RepositoryContent, err error)
GetFileContent retrieves the repository content at path. It returns an error when the fetch fails or when no file is found, so callers can distinguish a transient failure from an absent file.
func (*RestData) HasBuildInstructions ¶ added in v0.28.0
HasBuildInstructions returns true when the repository documents how to build the software from source per OSPS-DO-07.01. It is satisfied by a well-known build automation or build documentation file (e.g. Makefile, BUILDING.md) in the repository root, .github, or docs directory, or by a build-related section heading in the README or CONTRIBUTING guide.
func (*RestData) HasSupportMarkdown ¶
returns true when a file with case insensitive name matching support.md is found in the root or forge directories or when the readme.md contains a heading named "Support"
func (*RestData) IsCodeRepo ¶
IsCodeRepo returns true if the repository contains any programming languages.
TODO: Consider using GitHub Linguist metadata (https://github.com/github-linguist/linguist/blob/main/lib/linguist/languages.yml) to distinguish between programming, markup, data, and prose content types for more nuanced repository classification.
func (*RestData) MakeApiCall ¶
type SecurityPolicy ¶ added in v0.28.0
SecurityPolicy holds the repository's SECURITY.md as discovered through the GitHub API. Present is set when checkFile locates the file in the root or .github directory; Content holds its decoded body when it could be fetched.
type SecurityPosture ¶
type SecurityPosture interface {
// PreventsPushingSecrets and ScansForSecrets report the push-protection and
// secret-scanning settings observed in GitHub's security_and_analysis block.
// They are false when the block was not readable — check SecretScanningObservable.
PreventsPushingSecrets() bool
ScansForSecrets() bool
DefinesPolicyForHandlingSecrets() bool
// SecretScanningObservable reports whether GitHub's security_and_analysis block
// was readable. GitHub returns it only to callers with admin access to the
// repository, so for repositories we do not administer the observed settings
// are unreadable — distinct from being disabled.
SecretScanningObservable() bool
// InsightsDeclaresSecretScanning reports a Security Insights self-declaration of
// secret-scanning tooling, independent of (and possibly instead of) GitHub's
// native settings.
InsightsDeclaresSecretScanning() bool
}
SecurityPosture defines an interface for accessing security-related metadata about a repository.
The secret-scanning signals come from two independent sources kept separate so callers can report which was found: PreventsPushingSecrets/ScansForSecrets are the settings GitHub actually observed, and InsightsDeclaresSecretScanning is a project self-declaration. SecretScanningObservable reports whether GitHub's settings were readable at all.
type WorkflowBlob ¶ added in v0.27.0
type WorkflowBlobObject ¶ added in v0.27.0
type WorkflowBlobObject struct {
Blob WorkflowBlob `graphql:"... on Blob"`
}
type WorkflowFile ¶ added in v0.27.0
WorkflowFile is a single workflow definition with its contents already decoded.
Truncated marks a file GitHub declined to return in full. It is reported rather than dropped so callers can tell "inspected and clean" apart from "never inspected" — see checkAllWorkflows.
type WorkflowPermissions ¶
type WorkflowTreeEntry ¶ added in v0.27.0
type WorkflowTreeEntry struct {
Name string
Path string
Type string
Mode int
Object *WorkflowBlobObject `graphql:"object"`
}
WorkflowTreeEntry is one entry in the fetched directory. Type is "blob" for files; Object is nil for entries with no inspectable contents.