Documentation
¶
Overview ¶
Package secretguard defines opaque SDK contracts for the secrets-guard ingress stage.
Consumers receive Matcher / MatcherResolver capabilities that scan and redact without exposing raw catalog values. Decision.Validate rejects malformed decision shapes before the runner emits evidence or continues downstream. No type in this package returns secret bytes or accepts an environment reader at request time (design rules D3–D4).
Index ¶
- Constants
- func ActionForOutcome(o Outcome) string
- func DecisionMetricLabels(decision Decision) (action, outcome, sourceCategory string)
- func IsNilGuard(g Guard) bool
- func IsNilObserver(o Observer) bool
- func WithIngressAttribution(ctx context.Context, a IngressAttribution) context.Context
- func WithRequestMatcher(ctx context.Context, m Matcher) context.Context
- type AuditFailurePolicy
- type ContextMatcherResolver
- type Decision
- type DecisionEvent
- type ExecutionConfig
- type FailureMode
- type Finding
- type Guard
- type IngressAttribution
- type Matcher
- type MatcherResolver
- type Meta
- type Observer
- type ObserverFunc
- type Outcome
- type Services
- type SourceCategory
Constants ¶
const ( QuarantineResultCommitted = "committed" QuarantineResultFailed = "failed" QuarantineResultSkipped = "skipped" QuarantineResultNA = "n/a" )
QuarantineResult values for DecisionEvent.QuarantineResult.
Variables ¶
This section is empty.
Functions ¶
func ActionForOutcome ¶
ActionForOutcome maps a decision outcome to the stable action label used by metrics and audit events (block/redact/log/pass). Unknown outcomes map to "unknown".
func DecisionMetricLabels ¶
func IsNilGuard ¶
IsNilGuard reports whether g is nil or a typed-nil guard value.
func IsNilObserver ¶
IsNilObserver reports whether o is nil or a typed-nil observer value.
func WithIngressAttribution ¶
func WithIngressAttribution(ctx context.Context, a IngressAttribution) context.Context
WithIngressAttribution returns a child context carrying sanitized ingress attribution. A nil parent ctx is tolerated and substituted with context.TODO so the result is always non-nil.
func WithRequestMatcher ¶
WithRequestMatcher returns a child context carrying an opaque request-scoped Matcher. A nil parent is treated as context.TODO. A nil matcher clears/omits attachment semantics for consumers that check RequestMatcherFromContext.
Types ¶
type AuditFailurePolicy ¶
type AuditFailurePolicy string
AuditFailurePolicy controls observer-chain delivery failures.
const ( AuditFailClosed AuditFailurePolicy = "fail_closed" AuditBestEffort AuditFailurePolicy = "best_effort" )
type ContextMatcherResolver ¶
type ContextMatcherResolver struct{}
ContextMatcherResolver implements MatcherResolver by reading the request-scoped matcher from context. When no matcher is present it returns (nil, nil) and never reads the environment.
func (ContextMatcherResolver) Resolve ¶
func (ContextMatcherResolver) Resolve(ctx context.Context) (Matcher, error)
Resolve implements MatcherResolver.
type Decision ¶
type Decision struct {
Outcome Outcome
Findings []Finding
MutationCount int
ScanLimitHit bool
// FailureKind is a bounded operator-safe classifier (e.g. scan_limit, provider_error).
FailureKind string
// FailureReason is a bounded operator-safe reason; never secret material or excerpts.
FailureReason string
}
Decision is the Evaluate result: outcome, safe findings, and scan metadata.
type DecisionEvent ¶
type DecisionEvent struct {
Timestamp time.Time
EventID string
TraceID string
SessionID string
ALegID string
TurnID string
PrincipalID string
TenantID string
OrgID string
WorkspaceID string
PeerIP string
Source string
FrontendID string
Operation string
AgentIdentityDigest string
RequestedRoute string
RequestedModel string
Findings []Finding
Action string
Outcome Outcome
AccessMode string
ConfigVersion string
QuarantineResult string
BackendDispatched bool
GuardID string
ScanLimitHit bool
}
DecisionEvent is one secret-safe structured audit record for a guard decision. It must never carry secret values, prompt excerpts, bearer/resume tokens, or reversible fingerprints.
type ExecutionConfig ¶
type ExecutionConfig struct {
MatcherResolver MatcherResolver
DecisionObserver Observer
AuditFailurePolicy AuditFailurePolicy
AccessMode string
ConfigVersion string
// CatalogEntryCount, SourceCategories, and CatalogAction mirror the
// operator diagnostics inventory for the composed static catalog.
CatalogEntryCount int
SourceCategories []string
CatalogAction string
}
ExecutionConfig carries generation-composed secret-guard execution configuration bound by the standard distribution into the ordinary extension plane set. Guards themselves travel on PlaneSecretGuards; this struct carries the engine-composed matcher, audit, policy, and diagnostics posture that generic runtime execution needs alongside them.
func CloneExecutionConfig ¶
func CloneExecutionConfig(in *ExecutionConfig) *ExecutionConfig
CloneExecutionConfig deep-copies an execution configuration for frozen-set isolation: the container struct and the categories slice are copied, while the shared service capabilities (MatcherResolver, DecisionObserver) are intentionally preserved by reference — they are immutable engine handles, not configuration. A nil input yields nil, preserving NilSkip semantics.
func (ExecutionConfig) IsZero ¶
func (c ExecutionConfig) IsZero() bool
IsZero reports whether c carries no composed execution configuration (secret guard disabled for the generation).
type FailureMode ¶
type FailureMode int
FailureMode selects how the secret-guard runner treats a non-nil error from Evaluate.
const ( FailureModeUnspecified FailureMode = iota // FailOpen continues after recording a safe failure outcome. FailOpen // FailClosed stops the request and returns a policy failure. FailClosed )
type Finding ¶
type Finding struct {
SecretRefName string
Aliases []string
SourceCategory SourceCategory
Location string
OccurrenceCount int
}
Finding is safe match metadata. It must never carry a secret value or content excerpt.
type Guard ¶
type Guard interface {
ID() string
Order() int
FailureMode() FailureMode
Evaluate(ctx context.Context, call *lipapi.Call, meta Meta, services Services) (Decision, error)
}
Guard evaluates one secrets-guard feature instance against a canonical call.
func MaterializeSorted ¶
MaterializeSorted returns a defensive copy of guards sorted by Order ascending and then ID. Stable sorting preserves original order for exact ties.
type IngressAttribution ¶
type IngressAttribution struct {
PeerIP string
FrontendID string
Operation string
UserAgentDigest string
AgentIdentityDigest string
DeviceID string
KeyID string
Fingerprint string
}
IngressAttribution is sanitized HTTP/auth attribution for Meta and audit. It must never carry bearer tokens, Authorization headers, or raw secret material. Zero value means absent.
func IngressAttributionFromContext ¶
func IngressAttributionFromContext(ctx context.Context) (IngressAttribution, bool)
IngressAttributionFromContext returns attribution attached with WithIngressAttribution, if any. A nil ctx is tolerated and returns (IngressAttribution{}, false).
type Matcher ¶
type Matcher interface {
ScanBytes(ctx context.Context, input []byte) ([]Finding, error)
ScanString(ctx context.Context, input string) ([]Finding, error)
RedactBytes(ctx context.Context, input []byte) (redacted []byte, findings []Finding, err error)
RedactString(ctx context.Context, input string) (redacted string, findings []Finding, err error)
}
Matcher scans and redacts textual inputs, returning only safe findings.
func RequestMatcherFromContext ¶
RequestMatcherFromContext returns the Matcher attached with WithRequestMatcher, if any. A nil ctx is tolerated and returns (nil, false).
type MatcherResolver ¶
MatcherResolver resolves the request-scoped opaque Matcher. Implementations own secret bytes privately.
type Meta ¶
type Meta struct {
TraceID string
Principal execview.PrincipalView
Scope scope.PrincipalScopeView
Session session.SessionView
Workspace workspace.WorkspaceView
PeerIP string
FrontendID string
Operation string
UserAgentDigest string
AgentIdentityDigest string
DeviceID string
KeyID string
Fingerprint string
}
Meta carries authoritative request context and sanitized ingress attribution. It must not include bearer tokens, resume tokens, or raw secret values.
type Observer ¶
type Observer interface {
OnSecretDecision(ctx context.Context, ev DecisionEvent) error
}
Observer receives secret-decision audit events.
func ChainObservers ¶
func ChainObservers(policy AuditFailurePolicy, observers ...Observer) Observer
ChainObservers returns an Observer that invokes observers in order. fail_closed stops and returns the first error; best_effort continues after errors.
type ObserverFunc ¶
type ObserverFunc func(ctx context.Context, ev DecisionEvent) error
ObserverFunc adapts a function to Observer.
func (ObserverFunc) OnSecretDecision ¶
func (f ObserverFunc) OnSecretDecision(ctx context.Context, ev DecisionEvent) error
type Outcome ¶
type Outcome string
Outcome is the secret-guard decision for one Evaluate invocation.
type Services ¶
type Services struct {
MatcherResolver MatcherResolver
}
Services are opaque capabilities available to a Guard. No raw secret accessor is provided.
type SourceCategory ¶
type SourceCategory string
SourceCategory classifies where a matched secret reference originated.
const ( SourceCategoryProxyEnv SourceCategory = "proxy_env" SourceCategoryPopularEnv SourceCategory = "popular_env" SourceCategoryOperatorEnv SourceCategory = "operator_env" SourceCategoryRequestCred SourceCategory = "request_credential" SourceCategoryUnknown SourceCategory = "unknown" )
Source Files