data

package
v0.28.0 Latest Latest
Warning

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

Go to latest
Published: Aug 1, 2026 License: Apache-2.0 Imports: 25 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var APIBase = "https://api.github.com"

Functions

func Loader

func Loader(config *config.Config) (payload any, err error)

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 ClientMock struct {
	Response *http.Response
	Err      error
}

func (*ClientMock) Do

func (c *ClientMock) Do(req *http.Request) (*http.Response, error)

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 HttpClient

type HttpClient interface {
	Do(req *http.Request) (*http.Response, error)
}

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 NewPayloadWithHTTPMock(base Payload, body []byte, statusCode int, httpErr error) Payload

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

func (p Payload) AddEvidence(evidence gemara.Evidence)

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 (p Payload) GetEvidence() []gemara.Evidence

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

type PrivateVulnReporting struct {
	Enabled bool
	Known   bool
}

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 ReleaseAsset struct {
	Name        string `json:"name"`
	DownloadURL string `json:"browser_download_url"`
}

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

func NewRestDataWithFailingClient(err error) *RestData

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

func (r *RestData) DependencyToolingConfig() string

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

func (r *RestData) FindFile(names ...string) string

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

func (r *RestData) FindFileInDirs(dirs, names []string) string

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

func (r *RestData) HasBuildInstructions() bool

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

func (r *RestData) HasSupportMarkdown() bool

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

func (r *RestData) IsCodeRepo() (bool, error)

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

func (r *RestData) MakeApiCall(endpoint string, isGithub bool) (body []byte, err error)

func (*RestData) Setup

func (r *RestData) Setup() error

type SecurityPolicy added in v0.28.0

type SecurityPolicy struct {
	Present bool
	Content string
}

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 WorkflowBlob struct {
	Text        string
	IsTruncated bool
}

type WorkflowBlobObject added in v0.27.0

type WorkflowBlobObject struct {
	Blob WorkflowBlob `graphql:"... on Blob"`
}

type WorkflowFile added in v0.27.0

type WorkflowFile struct {
	Name      string
	Path      string
	Content   string
	Truncated bool
}

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 WorkflowPermissions struct {
	DefaultPermissions    string `json:"default_workflow_permissions"`
	CanApprovePullRequest bool   `json:"can_approve_pull_request_reviews"`
}

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL