scan

type Finding struct {
	// Provider names the issuer of the credential: GitHub, Slack.
	Provider    string      `json:"provider"`
	Kind        detect.Kind `json:"kind"`
	Fingerprint string      `json:"fingerprint"`
	Token       string      `json:"-"`
	// Secret is the companion material of a credential made of several
	// strings, when it was found next to the token; see detect.Token.Secret.
	Secret           string `json:"-"`
	Redacted         string `json:"token"`
	ChecksumVerified bool   `json:"checksum_verified"`
	// Attribution is what the credential's own shape says about its owner,
	// such as the workspace id in a Slack token; known without --verify.
	Attribution string `json:"attribution,omitempty"`
	// Encrypted marks passphrase-protected material, useless without a
	// passphrase that may or may not have leaked with it; see detect.Token.
	Encrypted bool `json:"encrypted,omitempty"`
	// Opaque marks secret material of no recognised shape, a plaintext
	// Kubernetes Secret, which nothing can verify; see detect.KindInfo.
	Opaque       bool                 `json:"opaque,omitempty"`
	Verification *detect.Verification `json:"verification,omitempty"`
	// Revocation records what happened when patty asked the provider to revoke the credential.
	Revocation Revocation `json:"revocation,omitempty"`
	// Local lists where the same token is configured on this machine.
	Local []string `json:"local,omitempty"`
	// Unlocks lists the files in the scanned repositories the credential
	// opens, when its provider correlates findings with the content around
	// them: the sops files encrypted to an age identity.
	Unlocks   []Unlock   `json:"unlocks,omitempty"`
	Locations []Location `json:"locations"`
	// Occurrences counts objects the token appears in, across all locations.
	Occurrences int `json:"occurrences"`
}

type Location struct {
	Repo       string          `json:"repo"`
	Object     string          `json:"object"`
	ObjectType string          `json:"object_type"`
	Path       string          `json:"path,omitempty"`
	Line       int             `json:"line"`
	Commit     *gitrepo.Commit `json:"commit,omitempty"`
	// Refs contains the refs whose history includes the commit.
	Refs []string `json:"refs,omitempty"`
	// Orphaned is true when no ref reaches the commit anymore.
	Orphaned bool `json:"orphaned"`
	// Rewrite explains how the commit went unreachable on the server, when known.
	Rewrite string `json:"rewrite,omitempty"`
}

type Options struct {
	// Workers is the number of parallel `git cat-file` readers.
	Workers int
	// MaxObject skips objects larger than this many bytes.
	MaxObject int64
	// Ignore holds the token fingerprints and credential kinds to leave out
	// of the results.
	Ignore map[string]bool
	// Providers is the set of credential providers to look for. It is
	// required: the caller assembles it, so this package need not know any
	// provider. A nil registry is a programming error and panics.
	Providers *detect.Registry
	// Verify checks each credential found against its provider's API.
	Verify bool
}

type Remote struct {
	Rewrites []Rewrite
	// Contributors are GitHub logins, as the repository's contributors
	// endpoint lists them; the scan adds the logins it reads from noreply
	// author addresses itself.
	Contributors []string
}

type Result struct {
	Target   string    `json:"target"`
	Findings []Finding `json:"findings"`
	Stats    Stats     `json:"stats"`
	Notes    []string  `json:"notes,omitempty"`
	// Files is true when the target is a file tree with no repository
	// behind it, a plain directory or a single file; its findings have no
	// history.
	Files   bool   `json:"files,omitempty"`
	Err     error  `json:"-"`
	Error   string `json:"error,omitempty"`
	Skipped bool   `json:"skipped,omitempty"`
}

type Revocation string

type Rewrite struct {
	SHA         string
	Description string
}

type RunOptions struct {
	Options
	// Cache holds the mirrors of GitHub targets.
	Cache *disk.Cache
	// Keep leaves mirrors in the cache after the scan for faster re-runs.
	Keep bool
	// Auth is used for HTTPS clones; nil for anonymous.
	Auth *gitrepo.Auth
	// GitHub is needed for the activity feed; nil disables it.
	GitHub *github.Client
	// Rewrites fetches commits the activity feed reports as force-pushed or deleted.
	Rewrites bool
	// ActivityPages caps the activity feed pages read per type and repository.
	ActivityPages int
	// Parallel is the number of repositories processed at once.
	Parallel int
	// Progress receives phase messages; may be nil.
	Progress func(target, msg string)
}

type Stats struct {
	Objects     int           `json:"objects"`
	Scanned     int           `json:"scanned"`
	Skipped     int           `json:"skipped_large"`
	Bytes       int64         `json:"bytes"`
	Refs        int           `json:"refs"`
	Orphaned    int           `json:"orphaned_commits"`
	Rewrites    int           `json:"rewrites_fetched"`
	Unavailable int           `json:"rewrites_unavailable"`
	Disk        int64         `json:"disk_bytes,omitempty"`
	Duration    time.Duration `json:"-"`
}

type Summary struct {
	// Repos counts every target, repository or not; Files the ones scanned
	// as files on disk only.
	Repos    int
	Files    int
	Failed   int
	Skipped  int
	Tokens   int
	Active   int
	Bytes    int64
	Objects  int
	Duration time.Duration
}

type Unlock struct {
	Repo string `json:"repo"`
	Path string `json:"path"`
	// Detail is what the file says about the credential when the path
	// alone does not: the names and expiry of the certificate a private
	// key belongs to.
	Detail string `json:"detail,omitempty"`
}