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
- Variables
- func And(base, scope labelfilter.Filter) labelfilter.Filter
- func FollowScope(tx *gorm.DB, sspID uuid.UUID, base labelfilter.Filter) (labelfilter.Filter, error)
- func MatchHash(labels []relational.ScopeLabel) string
- func Normalize(labels []relational.ScopeLabel) ([]relational.ScopeLabel, string, error)
- func ToFilter(entries []relational.SSPScopeEntry) (labelfilter.Filter, bool)
- type LearnResult
- type Scope
- type ScopeWouldEmptyError
- type Service
- func (s *Service) AddEntry(sspID uuid.UUID, labels []relational.ScopeLabel, actor *uuid.UUID) (relational.SSPScopeEntry, error)
- func (s *Service) AddException(sspID uuid.UUID, labels []relational.ScopeLabel, actor *uuid.UUID) (relational.SSPScopeException, error)
- func (s *Service) DeleteException(sspID, exceptionID uuid.UUID) error
- func (s *Service) Filter(sspID uuid.UUID) (labelfilter.Filter, bool, error)
- func (s *Service) Get(sspID uuid.UUID) (Scope, error)
- func (s *Service) Learn(tx *gorm.DB, sspID, templateID uuid.UUID, entries [][]relational.ScopeLabel) (LearnResult, error)
- func (s *Service) ReconcileAllAutoFilters(ctx context.Context) (int, error)
- func (s *Service) ReconcileAutoFilters(sspID uuid.UUID) (int, error)
- func (s *Service) SetAutoFilters(sspID uuid.UUID, enabled bool) error
- type SkippedEntry
Constants ¶
const ( MaxEntries = 500 MaxExceptions = 500 MaxLabelsPerEntry = 10 MaxLabelPartLength = 256 )
Limits on a scope, enforced on every write.
Variables ¶
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") )
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") )
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 (*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 ¶
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 ¶
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 ¶
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 ¶
ReconcileAllAutoFilters reconciles every SSP with automatic filters on. An SSP that fails does not stop the others; the errors are joined.
func (*Service) ReconcileAutoFilters ¶
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.
type SkippedEntry ¶
type SkippedEntry struct {
Labels []relational.ScopeLabel
Reason string
}
SkippedEntry is a learned entry that Learn could not store, with the reason.