vcs

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Jul 12, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ProviderGitHub = "github"
	ProviderGitLab = "gitlab"
)

ProviderGitHub / ProviderGitLab are the canonical provider strings written to installations.provider and returned by each client's Provider() method.

Variables

View Source 
var ErrChangeRequestNoChange = errors.New("change request produced no change")

ErrChangeRequestNoChange signals that the fetched file did not need any change for the given rule. Handlers turn this into 409 to render "already fixed" instead of "error".

View Source 
var ErrSettingsNotSupported = errors.New("repository-settings surface not supported for this provider")

ErrSettingsNotSupported is returned by clients for providers (currently GitLab) without an implemented settings audit/fix surface. The scan path treats it as a non-fatal "skip the settings audit".

Functions

func AutoFixableRepoSettingRules 

func AutoFixableRepoSettingRules() []scanner.RuleID

AutoFixableRepoSettingRules returns the sorted slice of rule IDs that have a registered auto-fixer. The SPA fetches this once to know which findings should render a Fix button.

func AutoFixableWorkflowRules 

func AutoFixableWorkflowRules() []scanner.RuleID

AutoFixableWorkflowRules returns the sorted slice of workflow rule IDs that the API can remediate via PR. The SPA fetches this once to render the per- finding Fix button for the right subset.

func ChangeBranchName 

func ChangeBranchName(ruleID scanner.RuleID, filePath string) string

ChangeBranchName composes the deterministic remediation branch name shared by GitHub PR and GitLab MR remediation.

func ChangeCommitMessage 

func ChangeCommitMessage(ruleID scanner.RuleID, filePath string) string

ChangeCommitMessage is the commit message used when committing the rewritten CI YAML file to the remediation branch.

func ChangeRequestBody 

func ChangeRequestBody(ruleID scanner.RuleID, filePath string, fixesCount int) string

func ChangeRequestTitle 

func ChangeRequestTitle(ruleID scanner.RuleID) string

ChangeRequestTitle / ChangeRequestBody are shared between providers so the PR and MR bodies read the same.

func IsAutoFixableRepoSetting 

func IsAutoFixableRepoSetting(ruleID scanner.RuleID) bool

IsAutoFixableRepoSetting reports whether the given rule has a registered auto-fixer. Web handlers and the CLI both use this to decide whether to surface a "Fix" affordance for a finding.

func IsAutoFixableWorkflowRule 

func IsAutoFixableWorkflowRule(ruleID scanner.RuleID) bool

IsAutoFixableWorkflowRule reports whether the given rule has a workflow-YAML auto-fixer available. Used by the handler to decide between the repo-settings fix path and the workflow PR-fix path, and by the SPA to decide which findings get a Fix button.

func IsWorkflowPath 

func IsWorkflowPath(p string) bool

IsWorkflowPath reports whether p is a GitHub Actions workflow file (.github/workflows/*.yml|yaml). Exported for the PR-check path in pkg/api.

func StatusOf 

func StatusOf(err error) int

StatusOf reports the HTTP status code if err wraps a provider API error (*GitHubAPIError or *GitLabAPIError), else 0.

Types

type ChangeRequestResult 

type ChangeRequestResult struct {
	Provider     string         `json:"provider"`
	RuleID       scanner.RuleID `json:"rule_id"`
	File         string         `json:"file"`
	FixesApplied int            `json:"fixes_applied"`
	URL          string         `json:"url"`    // PR html_url for GitHub, MR web_url for GitLab
	Number       int            `json:"number"` // PR number for GitHub, MR iid for GitLab
	BranchName   string         `json:"branch_name"`
	Reused       bool           `json:"reused"`    // true when an existing PR/MR was returned without re-fixing
	NoChange     bool           `json:"no_change"` // true when FixBytes produced no diff
}

ChangeRequestResult describes the outcome of FixWorkflow. The single result shape covers both GitHub Pull Requests and GitLab Merge Requests; the handler envelope (handleFixFinding) carries the provider so the SPA can label the link "Pull request" vs "Merge request".

type CheckRunAnnotation 

type CheckRunAnnotation struct {
	Path      string `json:"path"`
	StartLine int    `json:"start_line"`
	EndLine   int    `json:"end_line"`
	Level     string `json:"annotation_level"`
	Message   string `json:"message"`
	Title     string `json:"title,omitempty"`
}

CheckRunAnnotation is one inline annotation on a Check Run. Level is "failure" | "warning" | "notice".

type CheckRunParams 

type CheckRunParams struct {
	Name        string
	HeadSHA     string
	Conclusion  string // "success" | "failure" | "neutral"
	Title       string
	Summary     string
	Annotations []CheckRunAnnotation
}

CheckRunParams is the payload for creating a completed Check Run.

type GitHubAPIError 

type GitHubAPIError struct {
	Method string
	URL    string
	Status int
	Body   string
}

GitHubAPIError is returned by do() (and therefore wraps every non-2xx response) so callers can distinguish "not found" from other failures via errors.As, while the .Error() string format stays identical to the legacy `github METHOD URL: status N: BODY` shape that older callers grep with strings.Contains.

func (*GitHubAPIError) Error 

func (e *GitHubAPIError) Error() string

type GitHubClient 

type GitHubClient struct {
	// contains filtered or unexported fields
}

GitHubClient talks to the GitHub REST API on behalf of a GitHub App.

func NewBareGitHubClient 

func NewBareGitHubClient(opts ...Option) *GitHubClient

NewBareGitHubClient builds a GitHub client that never mints App JWTs — it can only call endpoints that accept a pre-obtained token (a user PAT or `gh auth token` output). The CLI uses this for repository-settings audits; the web app keeps using NewGitHubAppClient with the GitHub App.

func NewGitHubAppClient 

func NewGitHubAppClient(appID, privateKeyPEM string, opts ...Option) (*GitHubClient, error)

NewGitHubAppClient parses the app's PEM private key once at construction. When GitHub App creds are not configured (empty privateKeyPEM) the client is still returned (so the server can boot); its calls fail with a clear error until creds are set.

func (*GitHubClient) AuditSettings 

func (g *GitHubClient) AuditSettings(ctx context.Context, token string, repo RepoCoord, defaultBranch, htmlURL string) ([]scanner.Finding, error)

AuditSettings implements VCSClient: fetch the GitHub repository settings and run the settings scanner over them, returning the findings.

func (*GitHubClient) CreateCheckRun 

func (g *GitHubClient) CreateCheckRun(ctx context.Context, token, owner, repo string, p CheckRunParams) error

CreateCheckRun posts a completed Check Run for a commit. GitHub accepts at most 50 annotations per request; callers must pre-truncate. Requires the App to hold the `checks: write` permission.

func (*GitHubClient) DiscoverRepos 

func (g *GitHubClient) DiscoverRepos(ctx context.Context, token string) ([]RepoView, error)

DiscoverRepos lists every repository the token can read.

func (*GitHubClient) FetchRepoConfig 

func (g *GitHubClient) FetchRepoConfig(ctx context.Context, token, owner, repo, ref string) ([]byte, error)

FetchRepoConfig fetches the raw .pipefort.yml config bytes via the GitHub contents API, trying each candidate filename in precedence order. Returns (nil, nil) when no config file exists (a 404 on every candidate).

func (*GitHubClient) FetchRepoMeta 

func (g *GitHubClient) FetchRepoMeta(ctx context.Context, token, owner, repo string) (*RepoMeta, error)

FetchRepoMeta fetches repository metadata. The public scan uses it to distinguish "repo missing" from "repo has no workflows" (the trees API returns 404 for both) and to refuse private repos before spending any further API calls.

func (*GitHubClient) FetchRepositorySettings 

func (g *GitHubClient) FetchRepositorySettings(ctx context.Context, token, owner, repo, defaultBranch, htmlURL string) (*scanner.RepositoryContext, error)

FetchRepositorySettings issues the handful of GitHub API calls the repository-settings audit (pkg/scanner) needs and assembles the result. Each non-fatal 404 maps to a zero/false sentinel so callers can keep auditing even when one feature is unavailable; a 403 or any other status is returned as a *GitHubAPIError so the caller can surface a permission-degrade hint.

htmlURL is the repo's https://github.com/{owner}/{repo} URL — used only to build human remediation links in findings; pass "" if unknown.

func (*GitHubClient) FetchWorkflows 

func (g *GitHubClient) FetchWorkflows(ctx context.Context, token, owner, repo, ref string) ([]WorkflowFile, error)

FetchWorkflows lists .github/workflows/*.yml|yaml via the Git Trees API and downloads each file's bytes. No clone required, so this is fast and fits a serverless time budget.

func (*GitHubClient) FetchWorkflowsLimited 

func (g *GitHubClient) FetchWorkflowsLimited(ctx context.Context, token, owner, repo, ref string, maxFiles, maxBlobBytes int) (files []WorkflowFile, truncated bool, err error)

FetchWorkflowsLimited is FetchWorkflows with abuse caps for the anonymous public scan: maxFiles bounds how many workflow blobs are downloaded (0 = unlimited; truncated reports whether the cap was hit) and maxBlobBytes skips oversized blobs (0 = unlimited).

func (*GitHubClient) FixRepositorySettings 

func (g *GitHubClient) FixRepositorySettings(
	ctx context.Context,
	token, owner, repo, defaultBranch string,
	findings []scanner.Finding,
	dryRun bool,
) SettingsFixResult

FixRepositorySettings applies every auto-fixable finding in the input list against the GitHub API. Per-rule errors are recorded but never abort the batch — the caller can re-run on the residual set after addressing them.

When dryRun is true, no mutating requests are issued; the returned Applied list contains the actions that would have been taken.

func (*GitHubClient) FixSetting 

func (g *GitHubClient) FixSetting(ctx context.Context, token string, repo RepoCoord, defaultBranch string, ruleID scanner.RuleID, dryRun bool) (SettingsFixAction, error)

FixSetting dispatches to the GitHub-typed method.

func (*GitHubClient) FixSingleRepositorySetting 

func (g *GitHubClient) FixSingleRepositorySetting(
	ctx context.Context,
	token, owner, repo, defaultBranch string,
	ruleID scanner.RuleID,
	dryRun bool,
) (SettingsFixAction, error)

FixSingleRepositorySetting applies one specific rule's fixer. The web app uses this from POST /api/fix-finding to remediate one finding at a time.

func (*GitHubClient) FixWorkflow 

func (g *GitHubClient) FixWorkflow(ctx context.Context, token string, repo RepoCoord, defaultBranch, filePath string, ruleID scanner.RuleID) (ChangeRequestResult, error)

FixWorkflow dispatches to the GitHub-typed method.

func (*GitHubClient) FixWorkflowFile 

func (g *GitHubClient) FixWorkflowFile(
	ctx context.Context,
	token, owner, repo, defaultBranch, filePath string,
	ruleID scanner.RuleID,
) (ChangeRequestResult, error)

FixWorkflowFile is the 5-step Git Data dance that remediates one workflow finding by opening a PR. The provider-neutral result type (ChangeRequestResult) is shared with the GitLab MR remediation path so the handler envelope renders both the same way.

  1. Fetch the file's current bytes + blob SHA from the default branch.
  2. Re-scan the fresh content for the target rule, then run scanner.FixBytes against those findings; bail out if no fix matched (the file may have been fixed manually between the SPA scan and the user's Fix click).
  3. Create (or reuse) a deterministic branch from the default branch's HEAD.
  4. PUT the new content to that branch via the Contents API.
  5. Open a PR (or return the existing one) from the branch to the default branch.

We re-scan in step 2 (rather than trusting line/col from the SPA-cached finding) so the fix is always grounded in the actual content being mutated.

func (*GitHubClient) GetInstallation 

func (g *GitHubClient) GetInstallation(ctx context.Context, installationID int64) (*Installation, error)

GetInstallation fetches metadata for one installation (account login/type).

func (*GitHubClient) InstallationToken 

func (g *GitHubClient) InstallationToken(ctx context.Context, installationID int64) (string, error)

InstallationToken exchanges the app JWT for a short-lived installation token scoped to one installation's repositories.

func (*GitHubClient) ListOwnerRepos 

func (g *GitHubClient) ListOwnerRepos(ctx context.Context, token, owner string) ([]Repo, error)

ListOwnerRepos lists a GitHub owner's repositories by public listing, trying the org endpoint first and falling back to the user endpoint (the owner may be either). Paginated. Used by the CLI org-wide scan, which authenticates with a PAT rather than an installation.

func (*GitHubClient) ListPullRequestFiles 

func (g *GitHubClient) ListPullRequestFiles(ctx context.Context, token, owner, repo string, number int) ([]string, error)

ListPullRequestFiles returns the paths changed in a pull request (paginated). Used to skip the whole PR check when no workflow files were touched.

func (*GitHubClient) ListRepos 

func (g *GitHubClient) ListRepos(ctx context.Context, token string) ([]Repo, error)

ListRepos returns every repository the installation can access, following pagination.

func (*GitHubClient) LoadRepoConfig 

func (g *GitHubClient) LoadRepoConfig(ctx context.Context, token string, repo RepoCoord, ref string) ([]byte, error)

LoadRepoConfig dispatches to the GitHub-typed method.

func (*GitHubClient) LoadWorkflows 

func (g *GitHubClient) LoadWorkflows(ctx context.Context, token string, repo RepoCoord, ref string) ([]WorkflowFile, error)

LoadWorkflows dispatches to the GitHub-typed method.

func (*GitHubClient) Provider 

func (g *GitHubClient) Provider() string

Provider returns the canonical provider string.

type GitLabAPIError 

type GitLabAPIError struct {
	Method string
	URL    string
	Status int
	Body   string
}

GitLabAPIError mirrors *GitHubAPIError so callers can branch on status via StatusOf().

func (*GitLabAPIError) Error 

func (e *GitLabAPIError) Error() string

type GitLabClient 

type GitLabClient struct {
	// contains filtered or unexported fields
}

GitLabClient talks to the GitLab REST API with a caller-supplied per-request bearer token. The same client instance handles both gitlab.com and self-hosted hosts; the host is supplied per call, falling back to defaultHost. Token minting/refresh and the OAuth token store live in the private pkg/api gitlabVCS wrapper — this client is store-agnostic.

func NewBareGitLabClient 

func NewBareGitLabClient(host string, opts ...Option) *GitLabClient

NewBareGitLabClient returns a GitLabClient for a caller-held token: the CLI uses this for --fix-mr against a user-supplied --gitlab-token. Pass an explicit host for self-hosted instances; gitlab.com is the default.

func NewGitLabClient 

func NewGitLabClient(defaultHost string, opts ...Option) *GitLabClient

NewGitLabClient builds a GitLab client for the given default host (empty → gitlab.com). The SaaS wrapper (pkg/api) supplies the configured host; the caller passes a pre-minted token to every method.

func (*GitLabClient) AuditSettings 

func (g *GitLabClient) AuditSettings(ctx context.Context, token string, repo RepoCoord, defaultBranch, htmlURL string) ([]scanner.Finding, error)

AuditSettings implements VCSClient. It fetches the GitLab project's configuration (merge policy, pipeline visibility, protected default branch, approvals) and runs the GitLab settings scanner over it.

func (*GitLabClient) CurrentUser 

func (g *GitLabClient) CurrentUser(ctx context.Context, host, token string) (login, avatarURL string, err error)

CurrentUser returns the OAuth identity (login, avatar URL) for the given token. The SaaS callback uses it to populate the installations row.

func (*GitLabClient) DiscoverRepos 

func (g *GitLabClient) DiscoverRepos(ctx context.Context, token string) ([]RepoView, error)

DiscoverRepos implements VCSClient. Paginates /projects?membership=true at developer access (the minimum required to read CI config + open MRs).

func (*GitLabClient) FetchProjectSettings 

func (g *GitLabClient) FetchProjectSettings(ctx context.Context, token string, repo RepoCoord, defaultBranch, htmlURL string) (*scanner.GitLabProjectContext, error)

FetchProjectSettings reads the GitLab project's configuration into a scanner.GitLabProjectContext. Approvals (Premium) and protected-branch reads degrade gracefully — a 404/403 leaves the corresponding fields nil/unfetched rather than failing the whole audit.

func (*GitLabClient) FixSetting 

func (g *GitLabClient) FixSetting(ctx context.Context, token string, repo RepoCoord, _ string, ruleID scanner.RuleID, dryRun bool) (SettingsFixAction, error)

FixSetting implements VCSClient for the two project-level settings that are safe to toggle via the projects API: enabling "pipelines must succeed" and disabling public pipelines. Protected-branch and approval fixes are left for manual remediation. dryRun reports the action without writing.

func (*GitLabClient) FixWorkflow 

func (g *GitLabClient) FixWorkflow(ctx context.Context, token string, repo RepoCoord, defaultBranch, filePath string, ruleID scanner.RuleID) (ChangeRequestResult, error)

FixWorkflow implements VCSClient — the 5-step MR-based remediation pipeline. Mirrors the GitHub PR pipeline in workflow_fixer.go.

func (*GitLabClient) LoadRepoConfig 

func (g *GitLabClient) LoadRepoConfig(ctx context.Context, token string, repo RepoCoord, ref string) ([]byte, error)

LoadRepoConfig implements VCSClient. Fetches the first present .pipefort.yml candidate from the project root at the given ref, or (nil, nil) when absent.

func (*GitLabClient) LoadWorkflows 

func (g *GitLabClient) LoadWorkflows(ctx context.Context, token string, repo RepoCoord, ref string) ([]WorkflowFile, error)

LoadWorkflows implements VCSClient. Returns the root .gitlab-ci.yml when present and walks the .gitlab-ci/ directory tree for any *.yml/*.yaml.

func (*GitLabClient) Provider 

func (g *GitLabClient) Provider() string

Provider returns the canonical provider string.

type Installation 

type Installation struct {
	ID      int64 `json:"id"`
	Account struct {
		Login     string `json:"login"`
		Type      string `json:"type"`
		AvatarURL string `json:"avatar_url"`
	} `json:"account"`
}

Installation describes the account an app is installed on.

type Option 

type Option func(*clientOptions)

Option customizes a GitHub or GitLab client at construction time. The two tuning knobs — a base-URL override and a custom *http.Client — are what tests (in this module and, via the vcstest helpers, in dependent modules) need to point a client at an httptest server. Production callers never pass options; the zero configuration talks to the real APIs.

func WithBaseURL 

func WithBaseURL(u string) Option

WithBaseURL overrides the API base URL. For GitHub this replaces https://api.github.com; for GitLab it replaces https://{host}/api/v4.

func WithHTTPClient 

func WithHTTPClient(h *http.Client) Option

WithHTTPClient supplies the *http.Client used for all requests.

type OrgScanOptions 

type OrgScanOptions struct {
	Ruleset       string
	Persona       scanner.Persona
	MinConfidence scanner.Confidence
	Online        bool // run the online pin audits (needs network)
	Concurrency   int
}

OrgScanOptions tunes an org scan. Zero values are sensible: ruleset "all", persona regular, no min-confidence, online audits off, concurrency 4.

type OrgScanResult 

type OrgScanResult struct {
	Owner string
	Repos []RepoScanResult
}

OrgScanResult aggregates the per-repo results for one owner.

func (*OrgScanResult) Errors 

func (r *OrgScanResult) Errors() []string

Errors returns the repos that failed to scan, as "full_name: message".

func (*OrgScanResult) Flatten 

func (r *OrgScanResult) Flatten() ([]scanner.Finding, []scanner.ToxicCombo)

Flatten returns every repo's findings and combos as two aggregated slices, for feeding the existing reporters. Failed repos contribute nothing.

func (*OrgScanResult) SeverityLines 

func (r *OrgScanResult) SeverityLines() []string

SeverityLine returns a per-repo one-line summary ("owner/repo H:2 M:1 L:0"), skipping clean repos, for the console aggregate table.

type OrgScanner 

type OrgScanner struct {
	Client *GitHubClient
}

OrgScanner scans every repository owned by a GitHub org or user by fetching workflow YAML over the API (no cloning) and running the same in-memory scanner.ScanBytes the web app uses. It is the CLI counterpart to the web app's per-repo scan, aggregated across an owner — poutine's analyze_org.

func NewOrgScanner 

func NewOrgScanner() *OrgScanner

NewOrgScanner builds an org scanner over a bare (App-less) GitHub client.

func (*OrgScanner) Scan 

func (o *OrgScanner) Scan(ctx context.Context, token, owner string, opts OrgScanOptions) (*OrgScanResult, error)

Scan enumerates the owner's repositories and scans each with bounded concurrency. Per-repo failures are captured in the result, never fatal — only listing the owner's repos can fail the whole call.

type Repo 

type Repo struct {
	ID            int64  `json:"id"`
	Name          string `json:"name"`
	FullName      string `json:"full_name"`
	Private       bool   `json:"private"`
	HTMLURL       string `json:"html_url"`
	DefaultBranch string `json:"default_branch"`
	Owner         struct {
		Login string `json:"login"`
	} `json:"owner"`
}

Repo is the subset of repository metadata we persist.

type RepoCoord 

type RepoCoord struct {
	Owner string
	Name  string
	ID    string // provider repo id as a string ("" when unknown)
}

RepoCoord uniquely identifies a repository across providers. Owner+Name works for both GitHub (owner/name) and GitLab (group-path/project-name). ID is the provider's numeric repo id when callers know it — required for GitLab API URLs (which use the numeric project id), optional for GitHub.

type RepoMeta 

type RepoMeta struct {
	FullName      string `json:"full_name"`
	DefaultBranch string `json:"default_branch"`
	Private       bool   `json:"private"`
}

RepoMeta is the subset of GET /repos/{owner}/{repo} the public teaser scan needs: canonical naming, the branch to scan, and the private flag that gates anonymous access.

type RepoScanResult 

type RepoScanResult struct {
	FullName string
	Findings []scanner.Finding
	Combos   []scanner.ToxicCombo
	Err      error
}

RepoScanResult is one repository's outcome. Err is set (and Findings nil) when that repo could not be scanned; the org scan continues regardless.

type RepoView 

type RepoView struct {
	ProviderRepoID string // numeric (as string) for GitHub/GitLab
	Owner          string
	Name           string
	FullName       string
	Private        bool
	HTMLURL        string
	DefaultBranch  string
}

RepoView is the provider-neutral shape of one repository.

type SettingsFixAction 

type SettingsFixAction struct {
	RuleID      scanner.RuleID `json:"rule_id"`
	Description string         `json:"description"`        // human-readable: "Enabled secret scanning on acme/widgets"
	Endpoint    string         `json:"endpoint,omitempty"` // for debugging: "PATCH /repos/acme/widgets"
}

SettingsFixAction summarises one repository-settings remediation. The CLI prints these in both dry-run and applied modes; the web app returns one to the SPA so the Fix button can display "Enabled secret scanning".

type SettingsFixError 

type SettingsFixError struct {
	RuleID  scanner.RuleID `json:"rule_id"`
	Message string         `json:"message"`
}

SettingsFixError carries a per-rule failure so callers can render which rule failed and why without aborting the whole batch.

type SettingsFixResult 

type SettingsFixResult struct {
	Applied []SettingsFixAction `json:"applied"`           // mutations the API accepted (or would accept in dry-run)
	Skipped []scanner.RuleID    `json:"skipped,omitempty"` // rule IDs with no auto-fix (a no-op, not an error)
	Errors  []SettingsFixError  `json:"errors,omitempty"`  // per-rule failures; the rest of the run continues
	DryRun  bool                `json:"dry_run"`           // true if Apply was a no-op
}

SettingsFixResult aggregates the outcome of a FixRepositorySettings call.

type WorkflowFile 

type WorkflowFile struct {
	Path    string
	Content []byte
}

WorkflowFile is a single fetched workflow with its raw bytes.

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.