Documentation
¶
Overview ¶
Package engine provides the concrete secret catalog, Aho-Corasick exact pattern matching automaton, credential inventory discovery, and source policy implementation for the secretguard feature plugin.
The engine is internal to the secretguard feature tree and has zero dependencies on internal/core.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var PopularSecretEnvNames = []string{
"AWS_SECRET_ACCESS_KEY",
"AWS_SESSION_TOKEN",
"GITHUB_TOKEN",
"GH_TOKEN",
"GITLAB_TOKEN",
"NPM_TOKEN",
"PYPI_TOKEN",
"SLACK_BOT_TOKEN",
"STRIPE_SECRET_KEY",
"AZURE_CLIENT_SECRET",
"GOOGLE_API_KEY",
"DIGITALOCEAN_ACCESS_TOKEN",
"TWILIO_AUTH_TOKEN",
"SENDGRID_API_KEY",
"HEROKU_API_KEY",
"CLOUDFLARE_API_TOKEN",
"DATADOG_API_KEY",
"SENTRY_AUTH_TOKEN",
"TERRAFORM_TOKEN",
"VAULT_TOKEN",
}
PopularSecretEnvNames is the curated exact-name registry of common non-proxy credential environment variables loaded when SingleUserOptions.IncludePopularEnv is true. It remains the exact fallback for secret names not covered by generic `_API_KEY` / `_TOKEN` inference. Credential *paths*, *ids*, and profile names are intentionally omitted.
Explicitly not included (unless listed in IncludeEnv):
- AWS_ACCESS_KEY_ID
- AWS_PROFILE
- GOOGLE_APPLICATION_CREDENTIALS
- CURL_CA_BUNDLE
Functions ¶
func NewStaticMatcherResolver ¶
func NewStaticMatcherResolver(cat *Catalog, opts MatcherOptions) sdk.MatcherResolver
NewStaticMatcherResolver returns a MatcherResolver that always resolves to a matcher for cat. Callers pass MatcherOptions; composition typically enables PreserveKnownPrefixes.
Types ¶
type AccessMode ¶
type AccessMode uint8
AccessMode defines feature-local execution postures for secret sourcing. It is closed and internal to the feature engine; composition translates host access mode to this type.
const ( ModeSingleUser AccessMode = iota ModeMultiUser )
func (AccessMode) String ¶
func (m AccessMode) String() string
type Catalog ¶
type Catalog struct {
// contains filtered or unexported fields
}
Catalog is an immutable, opaque set of secret entries. No method returns secret values.
func BuildCatalog ¶
func BuildCatalog(raw []CatalogInput, minSecretBytes int) (*Catalog, error)
BuildCatalog copies qualifying inputs into a frozen catalog. Values shorter than minSecretBytes are dropped (default 8 when minSecretBytes <= 0). Identical values are deduplicated: primary ref is the lexicographically first name; remaining names become sorted aliases.
func (*Catalog) EntryCount ¶
EntryCount returns the number of distinct secret values in the catalog.
func (*Catalog) SourceCategories ¶
SourceCategories returns sorted unique source-category labels (safe inventory metadata).
type CatalogInput ¶
type CatalogInput struct {
Name string
Aliases []string
Value string
KnownPublicPrefix string
SourceCategory sdk.SourceCategory
}
CatalogInput is one named secret value for catalog construction. Value bytes are copied into private storage; callers should not rely on Catalog exposing them.
type Environment ¶
type Environment interface {
Lookup(name string) (value string, ok bool)
// Snapshot returns a defensive copy of KEY=VALUE pairs (os.Environ shape).
Snapshot() []string
}
Environment is the composition-injected process environment port. Multi-user construction must never call Lookup or Snapshot (D4).
type Matcher ¶
type Matcher struct {
// contains filtered or unexported fields
}
Matcher performs exact, case-sensitive secret matching against an immutable catalog. Scan and Redact are safe for concurrent use.
func NewMatcher ¶
NewMatcher returns an immutable matcher bound to cat with default options (full-length mask, no known-prefix preservation). A nil or empty catalog yields a matcher that never matches.
func NewMatcherWithOptions ¶
func NewMatcherWithOptions(cat *Catalog, opts MatcherOptions) *Matcher
NewMatcherWithOptions returns an immutable matcher bound to cat using opts.
func (*Matcher) RedactBytes ¶
RedactBytes returns a copy of input with matched spans masked. With PreserveKnownPrefixes, a match that begins with the entry's KnownPublicPrefix keeps those prefix bytes and masks only the remainder.
func (*Matcher) RedactString ¶
RedactString returns a copy of input with matched spans masked.
type MatcherOptions ¶
MatcherOptions controls redaction behavior for a Matcher. Zero value masks the full match with '*'.
type SingleUserOptions ¶
type SingleUserOptions struct {
IncludePopularEnv bool
IncludeEnv []string
ExcludeEnv []string
MinSecretBytes int
// Matcher controls redaction presentation for the composed static matcher.
// Zero value means composition defaults (preserve known prefixes, mask '*').
Matcher MatcherOptions
// MatcherConfigured is true when Matcher was set from decoded feature YAML.
// When false, NewSingleUserSource applies composition defaults for Matcher.
MatcherConfigured bool
}
SingleUserOptions configures single-user environment catalog loading.
type Source ¶
type Source interface {
AccessMode() AccessMode
// MatcherResolver returns an opaque resolver; implementations own secret bytes privately.
MatcherResolver() sdk.MatcherResolver
// EntryCount is safe inventory metadata (names/values are never returned).
EntryCount() int
// SourceCategories returns bounded source-category labels present in the catalog.
SourceCategories() []string
}
Source is an opaque composition-owned secret source. It must not expose raw catalog values.
func ComposeSource ¶
func ComposeSource(mode AccessMode, featureEnabled bool, env Environment, opts SingleUserOptions) (Source, error)
ComposeSource selects the secret source policy from effective access mode and feature enablement. Disabled performs no environment access. Multi-user never calls env (D4). Feature plugin YAML parsing remains Phase 4; callers pass composition-neutral options.
func NewDisabledSource ¶
func NewDisabledSource() Source
NewDisabledSource returns an empty source used when the secrets-guard feature is disabled. It performs no environment access. AccessMode reports ModeSingleUser as a neutral default (feature-disabled posture); EntryCount is 0 and Resolve returns (nil, nil).
func NewMultiUserSource ¶
func NewMultiUserSource(env Environment) (Source, error)
NewMultiUserSource builds a request-credential-only source. It must not call env even when env is non-nil (security boundary, not validation).
func NewSingleUserSource ¶
func NewSingleUserSource(env Environment, opts SingleUserOptions) (Source, error)
NewSingleUserSource loads the name-preserving environment catalog via Snapshot, proxy credential matching, optional popular exact/inferred names, and include/exclude lists.
Source Files