history

Documentation

Overview

Package history contains logic for tracking evaluation history

Index

• Constants
• Variables
• type AlertFilter
• type Direction
• type EntityNameFilter
• type EntityTypeFilter
• type EvaluationHistoryService
  • func NewEvaluationHistoryService(providerManager manager.ProviderManager, opts ...options) EvaluationHistoryService
• type Filter
• type FilterOpt
  • func WithAlert(alert string) FilterOpt
  • func WithEntityName(entityName string) FilterOpt
  • func WithEntityType(entityType string) FilterOpt
  • func WithFrom(from time.Time) FilterOpt
  • func WithProfileName(profileName string) FilterOpt
  • func WithProjectID(projectID uuid.UUID) FilterOpt
  • func WithProjectIDStr(projectID string) FilterOpt
  • func WithRemediation(remediation string) FilterOpt
  • func WithStatus(status string) FilterOpt
  • func WithTo(to time.Time) FilterOpt
• type ListEvaluationCursor
  • func ParseListEvaluationCursor(payload string) (*ListEvaluationCursor, error)
• type ListEvaluationFilter
  • func NewListEvaluationFilter(opts ...FilterOpt) (ListEvaluationFilter, error)
• type ListEvaluationHistoryResult
• type OneEvalHistoryAndEntity
• type ProfileNameFilter
• type ProjectFilter
• type RemediationFilter
• type StatusFilter
• type TimeRangeFilter

Constants

const (
	// Next represents the next page.
	Next = Direction("next")
	// Prev represents the prev page.
	Prev = Direction("prev")
)

Variables

var (
	// ErrMalformedCursor represents errors in the cursor payload.
	ErrMalformedCursor = errors.New("malformed cursor")
	// ErrInvalidProjectID is returned when project id is missing
	// or malformed form the filter.
	ErrInvalidProjectID = errors.New("invalid project id")
	// ErrInvalidTimeRange is returned the time range from-to is
	// either missing one end or from is greater than to.
	ErrInvalidTimeRange = errors.New("invalid time range")
	// ErrInclusionExclusion is returned when both inclusion and
	// exclusion filters are specified on the same field.
	ErrInclusionExclusion = errors.New("inclusion and exclusion filter specified")
	// ErrInvalidIdentifier is returned when an identifier
	// (e.g. entity name) is empty or malformed.
	ErrInvalidIdentifier = errors.New("invalid identifier")
)

var (
	// DefaultCursor is a cursor starting from the beginning of
	// the data set.
	DefaultCursor = ListEvaluationCursor{
		Time:      time.UnixMicro(999999999999999999).UTC(),
		Direction: Next,
	}
)

Types

type AlertFilter

type AlertFilter interface {
	// AddAlert adds an alert setting for inclusion/exclusion in
	// the filter.
	AddAlert(string) error
	// IncludedAlerts returns the list of included alert settings.
	IncludedAlerts() []string
	// IncludedAlerts returns the list of excluded alert settings.
	ExcludedAlerts() []string
}

AlertFilter interface should be implemented by types implementing a filter on alert settings.

type Direction

type Direction string

Direction enumerates the direction of the Cursor.

type EntityNameFilter

type EntityNameFilter interface {
	// AddEntityName adds an entity name for inclusion/exclution
	// in the filter.
	AddEntityName(string) error
	// IncludedEntityNames returns the list of included entity
	// names.
	IncludedEntityNames() []string
	// ExcludedEntityNames returns the list of excluded entity
	// names.
	ExcludedEntityNames() []string
}

EntityNameFilter interface should be implemented by types implementing a filter on entity names.

type EntityTypeFilter

type EntityTypeFilter interface {
	// AddEntityType adds an entity type for inclusion/exclusion
	// in the filter.
	AddEntityType(string) error
	// IncludedEntityTypes returns the list of included entity
	// types.
	IncludedEntityTypes() []string
	// ExcludedEntityTypes returns the list of excluded entity
	// types.
	ExcludedEntityTypes() []string
}

EntityTypeFilter interface should be implemented by types implementing a filter on entity types.

type EvaluationHistoryService

type EvaluationHistoryService interface {
	// StoreEvaluationStatus stores the result of this evaluation in the history table.
	// Returns the UUID of the evaluation status, and the UUID of the rule-entity
	StoreEvaluationStatus(
		ctx context.Context,
		qtx db.Querier,
		ruleID uuid.UUID,
		profileID uuid.UUID,
		entityType db.Entities,
		entityID uuid.UUID,
		evalError error,
		marshaledCheckpoint []byte,
	) (uuid.UUID, error)
	// ListEvaluationHistory returns a list of evaluations stored
	// in the history table.
	ListEvaluationHistory(
		ctx context.Context,
		qtx db.ExtendQuerier,
		cursor *ListEvaluationCursor,
		size uint32,
		filter ListEvaluationFilter,
	) (*ListEvaluationHistoryResult, error)
}

EvaluationHistoryService contains methods to add/query data in the history table.

func NewEvaluationHistoryService

func NewEvaluationHistoryService(providerManager manager.ProviderManager, opts ...options) EvaluationHistoryService

NewEvaluationHistoryService creates a new instance of EvaluationHistoryService

type Filter

type Filter interface{}

Filter is an empty interface to be implemented by structs representing filters. Its main purpose is to allow a generic definition of options functions.

type FilterOpt

type FilterOpt func(Filter) error

FilterOpt is the option type used to configure filters.

func WithAlert

func WithAlert(alert string) FilterOpt

WithAlert adds an alert string to the filter. The alert is added for inclusion unless it starts with a `!` characters, in which case it is added for exclusion.

func WithEntityName

func WithEntityName(entityName string) FilterOpt

WithEntityName adds an entity name string to the filter. The entity name is added for inclusion unless it starts with a `!` characters, in which case it is added for exclusion.

func WithEntityType

func WithEntityType(entityType string) FilterOpt

WithEntityType adds an entity type string to the filter. The entity type is added for inclusion unless it starts with a `!` characters, in which case it is added for exclusion.

func WithFrom

func WithFrom(from time.Time) FilterOpt

WithFrom sets the start of the time range, inclusive.

func WithProfileName

func WithProfileName(profileName string) FilterOpt

WithProfileName adds an profile name string to the filter. The profile name is added for inclusion unless it starts with a `!` characters, in which case it is added for exclusion.

func WithProjectID

func WithProjectID(projectID uuid.UUID) FilterOpt

WithProjectID adds a project id (uuid) to the filter. Whether a null uuid is valid or not is determined on a per-endpoint basis.

func WithProjectIDStr

func WithProjectIDStr(projectID string) FilterOpt

WithProjectIDStr adds a project id (string) to the filter. Whether a null uuid is valid or not is determined on a per-endpoint basis.

func WithRemediation

func WithRemediation(remediation string) FilterOpt

WithRemediation adds a remediation string to the filter. The remediation is added for inclusion unless it starts with a `!` characters, in which case it is added for exclusion.

func WithStatus

func WithStatus(status string) FilterOpt

WithStatus adds a status string to the filter. The status is added for inclusion unless it starts with a `!` characters, in which case it is added for exclusion.

func WithTo

func WithTo(to time.Time) FilterOpt

WithTo sets the end of the time range, exclusive.

type ListEvaluationCursor

type ListEvaluationCursor struct {
	Time      time.Time
	Direction Direction
}

ListEvaluationCursor is a struct representing a cursor in the dataset of historical evaluations.

func ParseListEvaluationCursor

func ParseListEvaluationCursor(payload string) (*ListEvaluationCursor, error)

ParseListEvaluationCursor interprets an opaque payload and returns a ListEvaluationCursor. The opaque paylaod is expected to be of one of the following forms

• `"+1257894000000000"` meaning the next page of data starting from the given timestamp excluded

• `"-1257894000000000"` meaning the previous page of data starting from the given timestamp excluded

• `"1257894000000000"` meaning the next page of data (default) starting from the given timestamp excluded

type ListEvaluationFilter

type ListEvaluationFilter interface {
	ProjectFilter
	EntityTypeFilter
	EntityNameFilter
	ProfileNameFilter
	StatusFilter
	RemediationFilter
	AlertFilter
	TimeRangeFilter
}

ListEvaluationFilter is a filter to be used when listing historical evaluations.

func NewListEvaluationFilter

func NewListEvaluationFilter(opts ...FilterOpt) (ListEvaluationFilter, error)

NewListEvaluationFilter is a constructor routine for ListEvaluationFilter objects.

It accepts a list of ListEvaluationFilterOpt options and performs validation on them, allowing only logically sound filters.

type ListEvaluationHistoryResult

type ListEvaluationHistoryResult struct {
	// Data is an ordered collection of evaluation events.
	Data []*OneEvalHistoryAndEntity
	// Next is an object usable as cursor to fetch the next
	// page. The page is absent if Next is nil.
	Next []byte
	// Prev is an object usable as cursor to fetch the previous
	// page. The page is absent if Prev is nil.
	Prev []byte
}

ListEvaluationHistoryResult is the return value of ListEvaluationHistory function.

type OneEvalHistoryAndEntity

type OneEvalHistoryAndEntity struct {
	*em.EntityWithProperties
	EvalHistoryRow db.ListEvaluationHistoryRow
}

OneEvalHistoryAndEntity is a struct representing a combination of an evaluation and an entity.

type ProfileNameFilter

type ProfileNameFilter interface {
	// AddProfileName adds a profile name for inclusion/exclusion
	// in the filter.
	AddProfileName(string) error
	// IncludedProfileNames returns the list of included profile
	// names.
	IncludedProfileNames() []string
	// ExcludedProfileNames returns the list of excluded profile
	// names.
	ExcludedProfileNames() []string
}

ProfileNameFilter interface should be implemented by types implementing a filter on profile names.

type ProjectFilter

type ProjectFilter interface {
	// AddProjectID adds a project id for inclusion in the filter.
	AddProjectID(uuid.UUID) error
	// GetProjectID returns the included project id.
	GetProjectID() uuid.UUID
}

ProjectFilter interface should be implemented by types implementing a filter on project id.

type RemediationFilter

type RemediationFilter interface {
	// AddRemediation adds a remediation for inclusion/exclusion
	// in the filter.
	AddRemediation(string) error
	// IncludedRemediations returns the list of included
	// remediations.
	IncludedRemediations() []string
	// ExcludedRemediations returns the list of excluded
	// remediations.
	ExcludedRemediations() []string
}

RemediationFilter interface should be implemented by types implementing a filter on remediation statuses.

type StatusFilter

type StatusFilter interface {
	// AddStatus adds a status for inclusion/exclusion in the
	// filter.
	AddStatus(string) error
	// IncludedStatuses returns the list of included statuses.
	IncludedStatuses() []string
	// ExcludedStatuses returns the list of excluded statuses.
	ExcludedStatuses() []string
}

StatusFilter interface should be implemented by types implementing a filter on statuses.

type TimeRangeFilter

type TimeRangeFilter interface {
	// SetFrom sets the start of the time range.
	SetFrom(time.Time) error
	// SetTo sets the end of the time range.
	SetTo(time.Time) error
	// GetFrom retrieves the start of the time range.
	GetFrom() *time.Time
	// GetTo retrieves the end of the time range.
	GetTo() *time.Time
}

TimeRangeFilter interface should be implemented by types implementing a filter based on time range.