detect

Documentation

Overview

Package detect includes the "API" of the rule-engine and includes public facing types that consumers of the rule engine should work with

Index

• Variables
• type DataSource
• type Finding
  • func (f *Finding) AddDataEntries(dataBatch map[string]interface{})
  • func (f *Finding) AddDataEntry(key string, data interface{})
  • func (f *Finding) GetData() map[string]interface{}
• type FindingDataStruct
• type Logger
• type Signal
• type SignalSourceComplete
• type Signature
• type SignatureContext
• type SignatureEventSelector
• type SignatureHandler
• type SignatureMetadata
• type WriteableDataSource

Variables

var ErrDataNotFound = errors.New("requested data was not found")

var ErrFailedToUnmarshal = errors.New("given value could not be unmarshaled")

var ErrKeyNotSupported = errors.New("queried key is not supported")

Types

type DataSource

type DataSource interface {
	// Get a value from the data source. Make sure the key matches one of the keys allowed in Keys.
	// The following errors should be returned for the appropriate cases:
	//
	//	- ErrDataNotFound - When the key does not match to any existing data
	//	- ErrKeyNotSupported - When the key used does not match to a support key
	//	- Otherwise errors may vary.
	Get(interface{}) (map[string]interface{}, error)
	// Version of the data fetched. Whenever the schema has a breaking change the version should be incremented.
	// Consumers of the data source should verify they are running against a support version before using it.
	Version() uint
	// The types of keys the data source supports.
	Keys() []string
	// JSON Schema of the data source's result. All Get results should conform to the schema described.
	Schema() string
	// Namespace of the data source (to avoid ID collisions)
	Namespace() string
	// ID of the data source, any unique name works.
	ID() string
}

type Finding

type Finding struct {

	// Data contains useful information about the context of the finding
	// added by signature authors.
	//
	// Deprecated: direct access to the Data field is allowed for historic reasons, but is unsafe.
	// The following methods should be used instead: AddDataEntry, AddDataEntries and GetData.
	Data        map[string]interface{}
	Event       protocol.Event // Event is the causal event of the Finding
	SigMetadata SignatureMetadata
	// contains filtered or unexported fields
}

Finding is the main output of a signature. It represents a match result for the signature business logic

func (*Finding) AddDataEntries

func (f *Finding) AddDataEntries(dataBatch map[string]interface{})

func (*Finding) AddDataEntry

func (f *Finding) AddDataEntry(key string, data interface{})

func (*Finding) GetData

func (f *Finding) GetData() map[string]interface{}

type FindingDataStruct

type FindingDataStruct interface {
	// ToMap converts the data to a map[string]interface{} for serialization
	ToMap() map[string]interface{}
}

findingDataStruct is the interface that types returned by signatures Data should implement to be serialized to protobuf when using GRPC

type Logger

type Logger interface {
	Debugw(format string, v ...interface{})
	Infow(format string, v ...interface{})
	Warnw(format string, v ...interface{})
	Errorw(format string, v ...interface{})
}

Logger interface to inject in signatures

type Signal

type Signal interface{}

Signal is a generic lifecycle event for a signature

type SignalSourceComplete

type SignalSourceComplete string

SignalSourceComplete signals that an input source the signature was subscribed to had ended

type Signature

type Signature interface {
	// GetMetadata allows the signature to declare information about itself
	GetMetadata() (SignatureMetadata, error)
	// GetSelectedEvents allows the signature to declare which events it subscribes to
	GetSelectedEvents() ([]SignatureEventSelector, error)
	// Init allows the signature to initialize its internal state
	Init(ctx SignatureContext) error
	// Close cleans the signature after Init operation
	Close()
	// OnEvent allows the signature to process events passed by the Engine. this is the business logic of the signature
	OnEvent(event protocol.Event) error
	// OnSignal allows the signature to handle lifecycle events of the signature
	OnSignal(signal Signal) error
}

Signature is the basic unit of business logic for the rule-engine

type SignatureContext

type SignatureContext struct {
	Callback      SignatureHandler
	Logger        Logger
	GetDataSource func(namespace string, id string) (DataSource, bool)
}

type SignatureEventSelector

type SignatureEventSelector struct {
	Source string
	Name   string
	Origin string
}

SignatureEventSelector represents events the signature is subscribed to

type SignatureHandler

type SignatureHandler func(found *Finding)

SignatureHandler is a callback function that reports a finding

type SignatureMetadata

type SignatureMetadata struct {
	ID          string
	Version     string
	Name        string
	EventName   string
	Description string
	Tags        []string
	Properties  map[string]interface{}
}

SignatureMetadata represents information about the signature

type WriteableDataSource

type WriteableDataSource interface {
	DataSource
	// Write values to keys in the data source. The values may not strictly match the schema defined
	// in the data source, however the implementation must be able to unmarshal it successfully to some form
	// where it can be eventually represented by the schema.
	//
	// The following errors should be returned for the appropriate cases:
	//
	// - ErrKeyNotSupported - When a given key does not match to supported key type
	// - ErrFailedToUnmarshal - When a value given could not be unmarshalled to an expected type
	// - Otherwise errors may vary.
	Write(data map[interface{}]interface{}) error
	// The types of values the data source supports writing.
	Values() []string
}