detect

Documentation

Overview

Package detect finds GitHub credentials in arbitrary byte content.

It is built for throughput: a scan is a handful of SIMD-accelerated substring searches for the fixed token prefixes followed by an exact shape check and, for the classic token families, an offline CRC32 checksum verification. A well-formed string with a wrong checksum is not a token; that single check removes the false positives a regex scanner has to live with.

Index

• func Checksum(random string) string
• func Fingerprint(value string) string
• func Redact(value string) string
• func Revocable(kind Kind) bool
• func RevokePage(kind Kind) string
• type Kind
• type Revoker
  • func NewRevoker() *Revoker
  • func (r *Revoker) Revoke(ctx context.Context, tokens []string) error
• type Token
  • func Find(content []byte) []Token
  • func (t Token) Fingerprint() string
• type Verification
  • func (v Verification) Issuer() string
• type Verifier
  • func NewVerifier() *Verifier
  • func (v *Verifier) Verify(ctx context.Context, tok Token) Verification
• type VerifyStatus

Functions

func Checksum

func Checksum(random string) string

Checksum computes the 6-character Base62 CRC32 checksum GitHub appends to the 30 random characters of a classic token. Exported so callers (and tests) can construct well-formed tokens without hard-coding any.

func Fingerprint

func Fingerprint(value string) string

Fingerprint returns the fingerprint of a raw token value.

func Redact

func Redact(value string) string

Redact hides the middle of a token, keeping enough of both ends to recognise it (`ghp_AbCd…WxYz`).

func Revocable

func Revocable(kind Kind) bool

Revocable reports whether GitHub's credential revocation endpoint accepts tokens of this kind. Installation tokens (ghs_) are the exception; they expire within an hour anyway.

func RevokePage

func RevokePage(kind Kind) string

RevokePage is where the owner revokes a token of this kind by hand.

Types

type Kind

type Kind string

Kind names a GitHub credential family.

const (
	// KindPAT is a classic personal access token (ghp_).
	KindPAT Kind = "github-pat"
	// KindOAuth is an OAuth app access token (gho_).
	KindOAuth Kind = "github-oauth"
	// KindUserToServer is a GitHub App user-to-server token (ghu_).
	KindUserToServer Kind = "github-user-to-server"
	// KindServerToServer is a GitHub App installation token (ghs_).
	KindServerToServer Kind = "github-server-to-server"
	// KindRefresh is a GitHub App refresh token (ghr_).
	KindRefresh Kind = "github-refresh"
	// KindFineGrained is a fine-grained personal access token (github_pat_).
	KindFineGrained Kind = "github-fine-grained-pat"
)

type Revoker

type Revoker struct {
	// BaseURL is the API root, https://api.github.com by default.
	BaseURL string
	Client  *http.Client
}

Revoker asks GitHub to revoke leaked credentials through POST /credentials/revoke. The endpoint is unauthenticated on purpose: it is meant for whoever finds a token, not only its owner, and GitHub notifies the owner of every revocation.

func NewRevoker

func NewRevoker() *Revoker

NewRevoker returns a Revoker against the public GitHub API.

func (*Revoker) Revoke

func (r *Revoker) Revoke(ctx context.Context, tokens []string) error

Revoke submits the token values for revocation, in batches the API accepts. GitHub processes the request asynchronously; a nil error means every batch was accepted, not that the tokens are already dead.

type Token

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 CRC32 checksum
	// that was verified offline. Classic tokens do; the fine-grained format
	// is matched on shape alone.
	ChecksumVerified bool
}

Token is one credential found in scanned content.

func Find

func Find(content []byte) []Token

Find returns every GitHub token in content, sorted by offset.

Two substring passes cover all six families: one for the shared "gh" stem of the classic prefixes and one for "github_pat_". Every candidate is then checked for exact shape and (classic families) checksum.

func (Token) Fingerprint

func (t Token) Fingerprint() string

Fingerprint returns a short, stable, non-reversible identifier for the token value: the first 16 hex characters of its SHA-256. It is safe to put in logs and allow-lists.

type Verification

type Verification struct {
	Status VerifyStatus `json:"status"`
	// Detail describes what the token gives access to: user and scopes, or
	// the number of repositories an installation token reaches.
	Detail string `json:"detail,omitempty"`
	// ClientID is the OAuth client id of the application the token was
	// issued to, when GitHub 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 token stops working, for tokens that expire.
	Expires string `json:"expires,omitempty"`
}

Verification is the result of Verifier.Verify.

func (Verification) Issuer

func (v Verification) Issuer() string

Issuer names the application a token was issued to: the known app name, else the raw client id, else "".

type Verifier

type Verifier struct {
	// BaseURL is the API root, https://api.github.com by default.
	BaseURL string
	Client  *http.Client
}

Verifier checks whether a token is still accepted by GitHub. It never stores or logs the token value.

func NewVerifier

func NewVerifier() *Verifier

NewVerifier returns a Verifier against the public GitHub API.

func (*Verifier) Verify

func (v *Verifier) Verify(ctx context.Context, tok Token) Verification

Verify performs one authenticated request with the token and classifies the response. A 401 is the only response treated as proof of revocation; anything but a clean 200 or 401 is reported as unknown.

type VerifyStatus

type VerifyStatus string

VerifyStatus is the outcome of checking a token against the GitHub API.

const (
	// StatusActive means the API accepted the token: it is live and must be revoked.
	StatusActive VerifyStatus = "active"
	// StatusRevoked means the API rejected the token as bad credentials.
	StatusRevoked VerifyStatus = "revoked"
	// StatusUnverifiable means the token family cannot be checked against the API.
	StatusUnverifiable VerifyStatus = "unverifiable"
	// StatusUnknown means the check could not be completed (network, rate limit).
	StatusUnknown VerifyStatus = "unknown"
)