scanner

type Config struct {
	Files     FilePolicy       `yaml:"files"`
	Rules     []RuleConfig     `yaml:"rules"`
	Detectors []DetectorConfig `yaml:"detectors"`
	// Filter is an optional list of filter rules. Each rule is an expr-lang
	// expression evaluated against every finding; what happens to a match depends
	// on the rule's action (drop it, or tag it). See FilterConfig and Filter for
	// the available variables. Empty means no filtering.
	Filter FilterConfigs `yaml:"filter"`
	// Correlations is an optional list of correlation rules. Each pairs a primary
	// finding with one or more partner findings seen just before it in the same
	// file; on a match the primary embeds the partners (which are dropped from the
	// top-level results) and all are tagged. See CorrelationConfig.
	Correlations []CorrelationConfig `yaml:"correlations"`
	// Info is an optional list of informational-finding rules. Each is an expr-lang
	// predicate over a value and its key name that, on a match, surfaces the value
	// as a levelInfo finding ("info:<id>") — a recognized non-credential identifier
	// such as a cloud account/tenant/subscription ID. They extend a built-in set
	// (see builtinInfoRules) and are evaluated before it. See InfoRuleConfig.
	Info []InfoRuleConfig `yaml:"info"`
	// Stopwords are extra non-secret words applied across all rules. As with the
	// built-in stopword set, a name-driven candidate
	// is dropped when its value contains (case-insensitively) any of these as a
	// substring. They extend, never replace, the always-on built-in set. Use this
	// to silence project-specific placeholders such as "redacted".
	Stopwords []string `yaml:"stopwords"`
	// JoinedEnvPrefixes are env-variable family prefixes joined to their kind
	// word with no separator — libpq's PGPASSWORD/PGHOST/PGUSER. Separator-
	// delimited families (PG_DB_*, MYSQL_*) group automatically; joined ones are
	// invisible to word splitting and must be named here for source-code
	// env-context enrichment to pair them. Matched case-insensitively.
	JoinedEnvPrefixes []string `yaml:"joined_env_prefixes"`
}

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

type Correlation struct {
	ID  string
	Tag string
	// contains filtered or unexported fields
}

type CorrelationConfig struct {
	ID       string           `yaml:"id"`
	Match    FindingMatcher   `yaml:"match"`
	Partners []FindingMatcher `yaml:"partners"`
	When     string           `yaml:"when"`
	Tag      string           `yaml:"tag"`
}

type CustomDetector struct {
	Name           string
	Keywords       []string // lowercased
	Regexes        []NamedRegex
	Primary        *regexp.Regexp // one of Regexes' patterns; supplies the reported value
	ExcludeRegexes []*regexp.Regexp
	ExcludeWords   []string // lowercased
	MinEntropy     float64
	// SecretType is the validated Finding.Type for this detector's matches, or
	// "" to derive it from the detector and key names.
	SecretType string
}

type Detector interface {
	Detect(file string, data []byte, set RuleSet) []Finding
}

type DetectorConfig struct {
	// Name labels the detector and appears in findings as "custom:<name>".
	Name string `yaml:"name"`
	// Keywords gate the detector: at least one must be present (case-insensitive)
	// in the value or its key name before the regexes are evaluated. An empty
	// list means the detector always runs its regexes.
	Keywords []string `yaml:"keywords"`
	// Regex maps a name to a pattern; every pattern must match the value for the
	// detector to fire. A pattern's first capture group, when present, is the
	// reported secret, otherwise the whole match is.
	Regex map[string]string `yaml:"regex"`
	// PrimaryRegexName selects which regex supplies the reported/entropy-checked
	// value; it defaults to the alphabetically first regex when omitted.
	PrimaryRegexName string `yaml:"primary_regex_name"`
	// ExcludeRegexesMatch drops a match whose primary value matches any of these.
	ExcludeRegexesMatch []string `yaml:"exclude_regexes_match"`
	// ExcludeWords drops a candidate when any of these appears (case-insensitive)
	// in the value or its key name.
	ExcludeWords []string `yaml:"exclude_words"`
	// Entropy, when > 0, drops matches whose primary value has Shannon entropy
	// (bits per symbol) below the threshold.
	Entropy float64 `yaml:"entropy"`
	// SecretType, when set, is the Finding.Type reported on this detector's
	// matches. It must be one of the secretType* vocabulary (e.g. "api-key",
	// "token"); compilation fails on an unknown value. When omitted, the type is
	// derived from the detector's name and the key name as usual.
	SecretType string `yaml:"secret_type"`
}

type DotenvDetector struct{}

type ExaminationFocus struct {
	File         string
	Path         string
	Line         int
	Name         string
	Value        string
	PrevFindings []Finding
}

type FilePolicy struct {
	Allow []string `yaml:"allow"`
	Deny  []string `yaml:"deny"`
}

type Filter struct {
	ID     string
	Action string
	// contains filtered or unexported fields
}

type FilterConfig struct {
	// ID labels the rule; it is the tag added to findings when Action is "tag".
	ID string `yaml:"id"`
	// Action is "filter" (drop matches, the default) or "tag" (keep and tag them).
	Action string `yaml:"action"`
	// Filter is the expr-lang expression evaluated against each finding.
	Filter string `yaml:"filter"`
}

type FilterConfigs []FilterConfig

type Finding struct {
	// File is the path to the source file. Top-level findings always set it; it is
	// cleared (and so omitted) on findings embedded under Correlated, since a
	// correlated partner is always in the same file as its primary — only its
	// in-file location (Path) is meaningful there.
	File string `json:"file,omitempty"`
	// Path is the in-document location: a structured locator such as "$.db.password"
	// for parsed config, or an INI "[section] line:N". It is empty (and omitted)
	// when File and Line already carry the full location, as in the plain
	// line-oriented formats.
	Path string `json:"path,omitempty"`
	// Line is the 1-based source line the finding sits on. It is 0 (and omitted)
	// when the format supplies no position, e.g. a relaxed-JSON fallback parse or
	// a structured path with no line index.
	Line int `json:"line,omitempty"`
	// Lang is the source language or config format of the file the finding came
	// from (e.g. "python", "json"). Omitted for unsupported file types.
	Lang string `json:"lang,omitempty"`
	// Level is the severity of the finding: "high" for a detected secret (the
	// default) or "info" for an informational match such as a recognized service
	// URL that is worth surfacing but is not itself a credential.
	Level               string  `json:"level,omitempty"`
	NamePath            string  `json:"name_path"`
	ValuePath           string  `json:"value_path"`
	Name                string  `json:"name"`
	Value               string  `json:"value"`
	RawValue            string  `json:"raw_value"`
	ValueSHA256         string  `json:"value_sha256"`
	Entropy             float64 `json:"entropy"`
	NameValueSimilarity float64 `json:"name_value_similarity"`
	// Type names what kind of secret the finding is (e.g. "password", "api-key",
	// "jwt" — see the secretType* constants), where Reason records why it was
	// flagged. Omitted on informational (levelInfo) findings, which are not
	// credentials.
	Type   string `json:"type,omitempty"`
	Reason string `json:"reason"`
	// Tags are free-form labels attached to the finding: the ID of any "tag"-action
	// filter rule the finding matched, and any correlation tag. The source language
	// or config format is carried in the dedicated Lang field rather than a tag.
	// Omitted when empty.
	Tags []string `json:"tags,omitempty"`
	// Filtered is set when the finding matched the config filter but was retained
	// (via -show-filtered) instead of dropped; FilteredReason holds the expression
	// that excluded it. Both are omitted from normal, unfiltered findings.
	Filtered       bool   `json:"filtered,omitempty"`
	FilteredReason string `json:"filtered_reason,omitempty"`
	Meta           *Meta  `json:"meta,omitempty"`
	// Git carries commit provenance when the finding came from a git history
	// scan rather than the working tree; nil (and omitted) otherwise.
	Git *GitProvenance `json:"git,omitempty"`
	// Correlated holds secondary findings folded into this primary by a
	// correlation rule (e.g. the client_id paired with this client_secret).
	// Embedded secondaries are removed from the top-level results and surface only
	// nested here.
	Correlated []Finding `json:"correlated,omitempty"`
}

type FindingFilter func(Finding) bool

type FindingMatcher struct {
	NameRegex   string `yaml:"name_regex"`
	ReasonRegex string `yaml:"reason_regex"`
	PathRegex   string `yaml:"path_regex"`
	Expr        string `yaml:"expr"`
}

type GitHistoryOptions struct {
	ScanRunOptions
	// MaxDepth, when positive, limits the scan to the N most recent commits
	// across all refs, ordered by committer time.
	MaxDepth int
	// MaxAge, when positive, skips commits whose committer time is more than
	// MaxAge before now (see ParseHumanDuration for accepting values like
	// "2 years"). Content introduced before the cutoff but still present in an
	// in-window commit is still scanned, attributed to the oldest in-window
	// commit containing it.
	MaxAge time.Duration
}

type GitProvenance struct {
	Commit     string `json:"commit"`
	Blob       string `json:"blob"`
	Author     string `json:"author,omitempty"`
	AuthorDate string `json:"author_date,omitempty"`
}

type INIDetector struct{}

type InfoRule struct {
	ID string
	// contains filtered or unexported fields
}

type InfoRuleConfig struct {
	// ID labels the rule and appears in findings as "info:<id>".
	ID string `yaml:"id"`
	// Match is the expr-lang predicate; a true result yields the info finding.
	Match string `yaml:"match"`
}

type JSONDetector struct{}

type JWT struct {
	Issuer     string                 `json:"issuer,omitempty"`
	Iat        int64                  `json:"iat,omitempty"`
	Expiration int64                  `json:"expiration,omitempty"`
	IsExpired  bool                   `json:"is_expired,omitempty"`
	Header     map[string]interface{} `json:"header,omitempty"`
	Extra      map[string]interface{} `json:"extra,omitempty"`
}

type Meta struct {
	JWT       *JWT                   `json:"jwt,omitempty"`
	Username  string                 `json:"username,omitempty"`
	AppId     string                 `json:"app_id,omitempty"`
	Host      string                 `json:"host,omitempty"`
	URL       string                 `json:"url,omitempty"`
	ClientID  string                 `json:"client_id,omitempty"`
	ClientKey string                 `json:"client_key,omitempty"`
	Extra     map[string]interface{} `json:"extra,omitempty"`
}

type NameRegexEntry struct {
	Name  string
	Regex string
}

type NamedRegex struct {
	Name  string
	Regex *regexp.Regexp
}

type PropertiesDetector struct{}

type Rule struct {
	NamePaths              []string
	ValuePaths             []string
	NameRegexes            []NamedRegex
	MinValueLen            int
	MinEntropy             float64
	HighEntropyThreshold   float64
	MaxNameValueSimilarity float64
	IgnoreNamePatterns     []*regexp.Regexp
	IgnoreValuePrefixes    []string
	IgnoreValuePatterns    []*regexp.Regexp
	// Stopwords are the effective extra non-secret words (lowercased) checked by
	// substring containment on top of the built-in stopword set. They come from
	// the global Config.Stopwords and are copied onto every rule at compile time
	// (see CompileConfig). Nil when none are configured.
	Stopwords []string
}

type RuleConfig struct {
	NamePaths  []string `yaml:"name_paths"`
	ValuePaths []string `yaml:"value_paths"`
	// NameRegexes is a list of name patterns. Each entry is either a bare regex
	// string or a {name, regex} mapping; a name matching any entry signals a
	// secret.
	NameRegexes []NameRegexEntry `yaml:"name_regexes"`
	MinValueLen int              `yaml:"min_value_len"`
	// MinEntropy, when > 0, gates name-driven findings: a value flagged because
	// its key name looks secret-y must have at least this Shannon entropy
	// (bits/symbol) or it is treated as a placeholder and dropped. Values that
	// carry a definite secret reason (JWT, private key, URL credentials) bypass
	// the gate.
	MinEntropy float64 `yaml:"min_entropy"`
	// HighEntropyThreshold, when > 0, enables a generic detector that flags any
	// value whose Shannon entropy meets the threshold, regardless of key name.
	HighEntropyThreshold float64 `yaml:"high_entropy_threshold"`
	// MaxNameValueSimilarity, when > 0, drops name-driven findings whose value is
	// at least this similar (0..1) to the key name — near-echoes such as
	// password="password1" or passwd="passw0rd" that the exact-echo check misses.
	// Similarity is the max of normalized Levenshtein and Jaro-Winkler.
	MaxNameValueSimilarity float64  `yaml:"max_name_value_similarity"`
	IgnoreNamePatterns     []string `yaml:"ignore_name_patterns"`
	IgnoreValuePrefixes    []string `yaml:"ignore_value_prefixes"`
	IgnoreValuePatterns    []string `yaml:"ignore_value_patterns"`
}

type RuleSet struct {
	Rules        []Rule
	Detectors    []CustomDetector
	Filters      []*Filter
	Correlations []Correlation
	// InfoRules recognize non-credential identifiers (cloud account/tenant/
	// subscription IDs) and surface them as levelInfo findings. See InfoRule.
	InfoRules []InfoRule
	// JoinedEnvPrefixes are the normalized (lowercased) no-separator env family
	// prefixes from Config.JoinedEnvPrefixes, read by the source detector's
	// env-context enrichment.
	JoinedEnvPrefixes []string
}

type ScanMode string

type ScanOptions struct {
	// IncludeFiltered keeps findings excluded by the config filter in the results,
	// marking each Filtered with its FilteredReason, instead of dropping them.
	IncludeFiltered bool
}

type ScanRunOptions struct {
	// Mode selects which file classes are visited; the zero value behaves as
	// ScanAll.
	Mode ScanMode
	// IncludeFiltered keeps findings excluded by the config filter in the
	// results, marking each Filtered with its FilteredReason, instead of
	// dropping them.
	IncludeFiltered bool
	// OnSkip, when non-nil, is called for each file that could not be scanned
	// (e.g. its bytes could not be read). Skipped files do not stop the walk.
	OnSkip func(path string, err error)
}

type SlnDetector struct{}

type SourceDetector struct{}

type ValuePattern struct {
	ID    string
	Regex *regexp.Regexp
	// Allow are per-rule allowlist regexes (carried from the source ruleset): when the
	// Regex matches but any Allow regex also matches the value, it is suppressed
	// (e.g. AWS example keys ending in EXAMPLE). Nil for the hand-curated rules.
	Allow []*regexp.Regexp
}

type XMLDetector struct{}

type YAMLDetector struct{}