sspscope

package
v0.22.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 28, 2026 License: AGPL-3.0 Imports: 16 Imported by: 0

Documentation

Overview

Package sspscope stores an SSP's scope: the labels that identify the SSP's evidence.

A scope is a list of entries; evidence is in scope when it matches any entry, and it matches an entry when it carries all of the entry's key=value labels. Users never delete an entry: they add an exception, which removes the entry and stops SSP templates from learning it again.

Index

Constants

View Source
const (
	MaxEntries         = 500
	MaxExceptions      = 500
	MaxLabelsPerEntry  = 10
	MaxLabelPartLength = 256
)

Limits on a scope, enforced on every write.

Variables

View Source
var (
	// ErrScopeEmpty is returned when a filter is asked to follow a scope with no entries.
	ErrScopeEmpty = errors.New("the SSP scope has no entries")
	// ErrScopeWouldEmpty is returned (as *ScopeWouldEmptyError) when a change would
	// leave the scope empty while filters follow it.
	ErrScopeWouldEmpty = errors.New("the change would leave the SSP scope empty while filters follow it")
)
View Source
var (
	// ErrInvalidLabels is returned when an entry's or exception's labels are malformed
	// (empty, too many, an empty or over-long key or value, a duplicate key).
	ErrInvalidLabels = errors.New("invalid scope labels")
	// ErrLimitExceeded is returned when a write would take the SSP past MaxEntries or
	// MaxExceptions.
	ErrLimitExceeded = errors.New("scope limit exceeded")
)
View Source
var (
	// ErrSSPNotFound is returned when the SSP does not exist.
	ErrSSPNotFound = errors.New("system security plan not found")
	// ErrExceptionNotFound is returned when the exception does not exist on the SSP.
	ErrExceptionNotFound = errors.New("scope exception not found")
	// ErrDuplicateEntry is returned when an entry matching the same evidence exists.
	ErrDuplicateEntry = errors.New("scope entry already exists")
	// ErrDuplicateException is returned when an exception with the same labels exists.
	ErrDuplicateException = errors.New("scope exception already exists")
)

Functions

func And

func And(base, scope labelfilter.Filter) labelfilter.Filter

And returns base AND scope. A base without a scope, or with an empty one ({"scope":{}}, the Evidence page's default), matches everything, so the result is scope alone.

func FollowScope

func FollowScope(tx *gorm.DB, sspID uuid.UUID, base labelfilter.Filter) (labelfilter.Filter, error)

FollowScope returns base AND the SSP's scope: the stored expression of a filter that follows the scope. It takes the SSP's scope lock for the rest of tx, so tx must be an open transaction and the filter must be written in it; a concurrent scope change then waits and rewrites the filter. It fails with ErrSSPNotFound or ErrScopeEmpty.

func MatchHash

func MatchHash(labels []relational.ScopeLabel) string

MatchHash is the SHA-256 hex of the sorted lower(key)=lower(value) pairs joined by "\n". Evidence labels match case-insensitively, so two entries that match the same evidence hash the same. labels must already be sorted by key (Normalize does that).

func Normalize

func Normalize(labels []relational.ScopeLabel) ([]relational.ScopeLabel, string, error)

Normalize is the single entry point for labels entering a scope. It trims keys and values, lower-cases keys (evidence label keys match case-insensitively), keeps value casing, sorts by key and rejects empty, duplicate-key, over-limit and hash-ambiguous input. It returns the normalized labels and their MatchHash.

func ToFilter

func ToFilter(entries []relational.SSPScopeEntry) (labelfilter.Filter, bool)

ToFilter converts entries to a label filter: the OR of the entries, each the AND of its labels as "=" conditions. Single-element levels collapse, and entries are ordered by MatchHash so the same scope always yields the same filter. ok is false when entries is empty.

Types

type LearnResult

type LearnResult struct {
	Added   []relational.SSPScopeEntry
	Skipped []SkippedEntry
}

LearnResult is what Learn added and what it skipped as invalid.

type Scope

type Scope struct {
	AutoFilters bool
	Entries     []relational.SSPScopeEntry
	Exceptions  []relational.SSPScopeException
}

Scope is an SSP's scope: its entries, exceptions and settings.

type ScopeWouldEmptyError

type ScopeWouldEmptyError struct {
	Following int64
}

ScopeWouldEmptyError names how many filters follow the scope that a change would empty.

func (*ScopeWouldEmptyError) Error

func (e *ScopeWouldEmptyError) Error() string

func (*ScopeWouldEmptyError) Is

func (e *ScopeWouldEmptyError) Is(target error) bool

type Service

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

Service reads and writes SSP scopes. Every write takes a per-SSP advisory lock, so a user edit and a template run on the same SSP do not interleave.

func NewService

func NewService(db *gorm.DB) *Service

NewService returns a Service over db.

func (*Service) AddEntry

func (s *Service) AddEntry(sspID uuid.UUID, labels []relational.ScopeLabel, actor *uuid.UUID) (relational.SSPScopeEntry, error)

AddEntry adds a manual entry. It fails with ErrDuplicateEntry when an entry matching the same evidence exists, and deletes an exception with the same labels: adding the entry says the user wants it.

func (*Service) AddException

func (s *Service) AddException(sspID uuid.UUID, labels []relational.ScopeLabel, actor *uuid.UUID) (relational.SSPScopeException, error)

AddException adds an exception and deletes the entry with the same labels, if any. It fails with ErrDuplicateException when the exception exists, and with ErrScopeWouldEmpty (*ScopeWouldEmptyError) when it would remove the last entry while filters follow the scope.

func (*Service) DeleteException

func (s *Service) DeleteException(sspID, exceptionID uuid.UUID) error

DeleteException deletes only the exception: the entry does not come back. A template run re-learns it if evidence still shows it, or the user adds it again.

func (*Service) Filter

func (s *Service) Filter(sspID uuid.UUID) (labelfilter.Filter, bool, error)

Filter returns the SSP's scope as a label filter. ok is false when the scope has no entries: an empty scope means the SSP has not declared its evidence, not "everything". It returns ErrSSPNotFound when the SSP does not exist.

func (*Service) Get

func (s *Service) Get(sspID uuid.UUID) (Scope, error)

Get returns the SSP's entries (oldest first), exceptions (oldest first) and settings.

func (*Service) Learn

func (s *Service) Learn(tx *gorm.DB, sspID, templateID uuid.UUID, entries [][]relational.ScopeLabel) (LearnResult, error)

Learn adds template-origin entries inside the caller's transaction, skipping entries that already exist, entries with an exception and repeats within entries. Entries that fail Normalize (an evidence value over the length limit, say) are skipped and reported in Skipped rather than failing the call. It never removes entries. tx must be an open transaction: the SSP's scope lock is transaction-scoped, so outside one it is released immediately.

func (*Service) ReconcileAllAutoFilters

func (s *Service) ReconcileAllAutoFilters(ctx context.Context) (int, error)

ReconcileAllAutoFilters reconciles every SSP with automatic filters on. An SSP that fails does not stop the others; the errors are joined.

func (*Service) ReconcileAutoFilters

func (s *Service) ReconcileAutoFilters(sspID uuid.UUID) (int, error)

ReconcileAutoFilters creates the SSP's missing automatic per-policy filters: one scope-following filter per _policy value of its in-scope latest evidence, with no controls or components. It never deletes or renames automatic filters, and never recreates one that was deleted. It is a no-op when automatic filters are off or the scope is empty. It returns how many filters it created.

func (*Service) SetAutoFilters

func (s *Service) SetAutoFilters(sspID uuid.UUID, enabled bool) error

SetAutoFilters turns automatic per-policy filters on or off for the SSP. Turning them on creates the missing automatic filters in the same transaction.

type SkippedEntry

type SkippedEntry struct {
	Labels []relational.ScopeLabel
	Reason string
}

SkippedEntry is a learned entry that Learn could not store, with the reason.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL