detect

type CommitterCorrelator interface {
	Correlator
	// Committers is handed the distinct GitHub logins of a repository's
	// authors and contributors and returns, per identifier (in the form
	// Identifiers reports them), what a match means: "matches octocat's
	// GitHub SSH key". It may fetch public data and is called once per
	// repository, after the scan, only when the repository holds a
	// credential of this provider.
	Committers(ctx context.Context, logins []string) map[string]string
}

type Configurable interface {
	Configure(env func(string) string)
}

type Correlator interface {
	// Observe returns the identifiers under which content names credentials
	// of this provider (the recipients an encrypted file lists), or nil when
	// the object is of no interest. It runs on every scanned object and has
	// to be cheap; it must not keep a reference to content.
	Observe(content []byte) []Sighting
	// Identifiers returns what the credential is known as in such content:
	// the public key of an identity. The scan matches them against what
	// Observe reported.
	Identifiers(tok Token) []string
}

type Document struct {
	Body []byte
	// Start is the byte offset of Body in the content it was cut from.
	Start int
	// contains filtered or unexported fields
}

type DryRunRevoker interface {
	DryRunRevoke(ctx context.Context, tok Token) error
}

type Kind string

type KindInfo struct {
	Kind Kind
	// Description is the human name: "personal access token (classic)".
	Description string
	// Revocable reports whether the provider's revocation endpoint accepts this kind.
	Revocable bool
	// RevokePage is where the owner revokes a credential of this kind by hand.
	RevokePage string
	// RevokeNote is added to the manual revocation advice when the API cannot
	// revoke the kind: what to check instead, or why it does not matter.
	RevokeNote string
	// RevokeEffect names a side effect of revoking through the API that is
	// easy to miss. The placeholder {app} stands for the issuing application.
	RevokeEffect string
	// AuditNote says how to find out whether a leaked credential of this kind
	// was used while it was exposed, and what the provider does on its own
	// when it spots the leak. Shown for every finding, revoked or not.
	AuditNote string
	// UnlocksLabel labels the advice line that lists what a credential of
	// this kind opens in the scanned repositories ("decrypts"). Set only for
	// the kinds of a Correlator.
	UnlocksLabel string
	// UnlocksNone is that line when nothing scanned names the credential.
	UnlocksNone string
	// PublicValue reports that Token.Value names the credential without
	// revealing it, such as a registry login's host and username whose
	// secret is the password in Token.Secret; the report shows it in full.
	PublicValue bool
	// Opaque reports that a finding of this kind names secret material of
	// no recognised shape, a plaintext Kubernetes Secret, which no provider
	// can verify. The report lists such findings after every credential it
	// can put a name to.
	Opaque bool
}

type LocalSources struct {
	// Env lists environment variables tools read the credential from.
	Env []string
	// EnvFiles lists environment variables whose value is the path of a
	// file holding the credential, or a list of such paths separated the
	// way PATH is.
	EnvFiles []string
	// ConfigFiles are relative to the XDG config directory (~/.config).
	ConfigFiles []string
	// HomeFiles are relative to the home directory.
	HomeFiles []string
	// Commands print a credential to stdout, such as `gh auth token`.
	Commands [][]string
}

type PathClassifier interface {
	// Classify returns the kind for a credential found under paths and
	// matched by the identifiers in matched, or "" to keep the kind Find
	// gave it. The scan applies it after attribution and correlation.
	Classify(tok Token, paths []string, matched []string) Kind
}

type Provider interface {
	// Name is how the provider is called in reports: "GitHub", "Slack".
	Name() string
	// Kinds describes every credential family the provider detects.
	Kinds() []KindInfo
	// Find returns every credential of this provider in content. Offsets
	// are set; line numbers are filled in by the Registry.
	Find(content []byte) []Token
	// Verify asks the provider whether the credential is still accepted.
	// Only the provider's explicit invalid-credentials answer is reported as
	// revoked; anything else that is not a clean acceptance is unknown.
	Verify(ctx context.Context, tok Token) Verification
	// Revoke asks the provider to revoke the given credentials. A nil error
	// means every request was accepted; the caller confirms the outcome with
	// Verify.
	Revoke(ctx context.Context, tokens []Token) error
	// LocalSources lists where tools keep this provider's credentials on a
	// developer machine.
	LocalSources() LocalSources
}

type ProximityCorrelator interface {
	Correlator
	// Adjacent returns the identifiers a credential of this kind adopts
	// from a sighting found in the same directory, or nil when the
	// sighting is not one it should.
	Adjacent(kind Kind, s Sighting) []string
}

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

type Secret struct {
	Namespace string
	Name      string
	// Type is the Secret's type, "" for Opaque.
	Type string
	// Offset is where the manifest's kind is written in the content.
	Offset int
	// Sops reports that the manifest carries a sops metadata block: its
	// values are ciphertext and nothing about them is a finding.
	Sops   bool
	Values []SecretValue
}

type SecretValue struct {
	Key string
	// Offset is where the key is written in the content, which is where a
	// finding inside the value is placed; End is where the next key, or the
	// document, starts. A provider's own finding between the two sits in
	// this value.
	Offset, End int
	// Value is the decoded material, nil when Skipped says why not.
	Value []byte
	// Skipped names the reason a value was left alone: empty, templated,
	// encrypted (a sops ENC[…] value), not base64, or too large.
	Skipped string
}

type ServerVerifier interface {
	AllowPrivateServers(allow bool)
}

type Sighting struct {
	ID string
	// Detail is shown next to the file that names the credential; empty
	// when the file itself says enough (a sops recipient list).
	Detail string
}

type Token struct {
	Kind  Kind
	Value string
	// Offset is the byte offset of the token in the scanned content.
	Offset int
	// Line is the 1-based line the token starts on.
	Line int
	// ChecksumVerified reports whether the token carries a checksum that
	// was verified offline. Classic GitHub tokens do; every other format is
	// matched on shape alone.
	ChecksumVerified bool
	// Attribution is what the token's own shape says about its owner, without
	// contacting the provider: a team id in a Slack token, for example. Empty
	// when the format carries nothing of the sort.
	Attribution string
	// Encrypted reports that the material is passphrase-protected and so
	// useless to whoever found it unless the passphrase leaked with it: an
	// encrypted private key. The report lists such findings after the ones
	// that are usable as they are.
	Encrypted bool
	// Secret is the material a credential needs besides Value when it is made
	// of several strings: the secret access key found next to an AWS key id,
	// and the session token of a temporary one. Its layout is the provider's
	// business. Value alone identifies the credential; Secret is never
	// printed, logged or fingerprinted.
	Secret string
}

type Verification struct {
	Status VerifyStatus `json:"status"`
	// Detail describes what the credential gives access to: user and scopes,
	// the workspace of a Slack token, the number of repositories an
	// installation token reaches.
	Detail string `json:"detail,omitempty"`
	// ClientID is the id of the application the credential was issued to,
	// when the provider reports one.
	ClientID string `json:"client_id,omitempty"`
	// App is the name of that application when patty knows the client id.
	App string `json:"app,omitempty"`
	// Expires is when the credential stops working, for credentials that expire.
	Expires string `json:"expires,omitempty"`
}

type VerifyStatus string