Documentation
¶
Overview ¶
Package github implements the github source plugin: lists repositories and organization members from a single GitHub organization and emits two evidence types — github_repository and github_org_member — suitable for SOC 2 branch-protection and 2FA coverage policies.
Per the KISS-no-DRY axiom (docs/architecture/04-source-plugins.md §The plugin contract), the plugin caches nothing across Collect calls. N policies bound to this plugin → N invocations of Collect.
Test injection: the API interface mirrors the pattern used by internal/sources/aws/iam — the concrete *httpAPI satisfies it, and unit tests inject an in-memory fake. The real HTTP adapter has no integration tests today (deferred — live API integration tests are out of scope for this batch).
Index ¶
Constants ¶
const ( EvidenceTypeRepository = "git_repository" EvidenceTypeDirectoryUser = "directory_user" )
Evidence type IDs this plugin emits.
EvidenceTypeRepository is the cross-vendor git_repository shape; GitHub is one of several substitutable source-code platforms (GitLab, Bitbucket, future Gitea/Azure DevOps). EvidenceTypeDirectoryUser is the cross-vendor directory_user shape — GitHub org members are one of several substitutable directory sources (AWS IAM, Okta, future Azure AD/LDAP).
const SourceID = "github"
SourceID is the registered ID for the github plugin instance.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type API ¶
type API interface {
// ListRepos returns all repos in the configured organization.
// Implementations must page transparently — callers receive the
// full list in one slice.
ListRepos(ctx context.Context) ([]Repo, error)
// ListOrgMembers returns all members of the configured org along
// with their 2FA state and role. 2FA state requires admin scope.
ListOrgMembers(ctx context.Context) ([]Member, error)
}
API is the subset of the GitHub REST API the plugin uses. Defining it as an interface lets tests inject a fake without making real network calls; the concrete *httpAPI satisfies it.
type Options ¶
type Options struct {
API API
Org string
// Now is injected so tests can produce deterministic CollectedAt
// values. Production callers leave it nil → time.Now().UTC().
Now func() time.Time
}
Options is the constructor input.
type Plugin ¶
type Plugin struct {
// contains filtered or unexported fields
}
Plugin is the in-process github source.
func New ¶
New constructs a Plugin around an explicit API implementation. Callers using the real GitHub REST API should use NewFromToken.
func NewFromToken ¶
NewFromToken constructs a Plugin backed by the real GitHub REST API using the supplied personal-access or app token. The plugin issues requests against api.github.com. Live integration tests are deferred.
func (*Plugin) Collect ¶
func (p *Plugin) Collect(ctx context.Context, req core.SlotRequest) ([]core.EvidenceRecord, error)
Collect returns records for every evidence type in req.AcceptedTypes that this plugin emits. A slot whose Accepts list includes both github types gets records for both in a single call. Records are sorted by ID within each type group; the collector splits them by Type for envelope writing.
type Repo ¶
type Repo struct {
Name string
DefaultBranch string
ProtectionOn bool
RequiredReviews int
// Branch-protection rule details (default branch).
RequiresSignedCommits bool
RequiresLinearHistory bool
AllowsForcePush bool
DismissStaleReviews bool
RequireCodeOwnerReviews bool
// Repository attributes.
IsPrivate bool
Archived bool
// Code-security and analysis features.
SecretScanningEnabled bool
PushProtectionEnabled bool
DependabotAlertsEnabled bool
CodeScanningEnabled bool
}
Repo is the subset of fields the plugin extracts from a repository listing. The plugin returns one record per Repo, augmented with branch-protection state and code-security settings queried via follow-up calls. Every field maps to a property of the git_repository evidence type so policies never read an absent field.
Source Files