Documentation
¶
Overview ¶
Package pluginkit provides the core plugin kit functionality for building Privateer plugins.
Package pluginkit provides the core plugin kit functionality for building Privateer plugins.
This file contains error definitions to streamline testing and log management.
Index ¶
- Variables
- type ApplyFunc
- type Change
- type ChangeManager
- func (cm *ChangeManager) AddChange(changeName string, change Change)
- func (cm *ChangeManager) Allow()
- func (cm *ChangeManager) Apply(changeName string, targetName string, changeInput any) (success bool, target any)
- func (cm *ChangeManager) Revert(changeName string)
- func (cm *ChangeManager) RevertAll()
- type DataLoader
- type EvaluationOrchestrator
- func (v *EvaluationOrchestrator) AddEvaluationSuite(catalogId string, loader DataLoader, steps map[string][]gemara.AssessmentStep) error
- func (v *EvaluationOrchestrator) AddEvaluationSuiteForAllCatalogs(loader DataLoader, steps map[string][]gemara.AssessmentStep) error
- func (v *EvaluationOrchestrator) AddLoader(loader DataLoader)
- func (v *EvaluationOrchestrator) AddReferenceCatalogs(dataDir string, files embed.FS) error
- func (v *EvaluationOrchestrator) AddRequiredVars(vars []string)
- func (v *EvaluationOrchestrator) Mobilize() error
- func (v *EvaluationOrchestrator) WriteResults() error
- type EvaluationSuite
- type RevertFunc
- type TestSet
Constants ¶
This section is empty.
Variables ¶
var ( CORRUPTION_FOUND = func(mod string) error { return errMod("target state may be corrupted! Halting to prevent futher damage. See logs for more information", mod) } NO_EVALUATION_SUITES = func(mod string) error { return errMod("no control evaluations provided by the plugin", mod) } EVAL_NAME_MISSING = func(mod string) error { return errMod("evaluationSuite name must not be empty", mod) } CONFIG_NOT_INITIALIZED = func(mod string) error { return errMod("configuration not initialized", mod) } NO_ASSESSMENT_STEPS_PROVIDED = func(mod string) error { return errMod("assessment steps not provided", mod) } NO_ASSESSMENT_REQS_PROVIDED = func(mod string) error { return errMod("assessment requirements not provided", mod) } EVAL_SUITE_CRASHED = func(mod string) error { return errMod("evaluation suite crashed", mod) } )
Error functions that require no parameters.
var ( EVALUATION_ORCHESTRATOR_NAMES_NOT_SET = func(serviceName, pluginName string, mod string) error { return errMod(fmt.Errorf("expected service and plugin names to be set. ServiceName='%s' PluginName='%s'", serviceName, pluginName), mod) } WRITE_FAILED = func(name, err string, mod string) error { return errMod(fmt.Errorf("failed to write results for evaluation suite. name: %s, error: %s", name, err), mod) } BAD_LOADER = func(pluginName string, err error, mod string) error { return errMod(fmt.Errorf("failed to load payload for %s: %s", pluginName, err), mod) } BAD_CATALOG = func(pluginName string, errMsg string, mod string) error { return errMod(fmt.Errorf("malformed data in catalog for %s: %s", pluginName, errMsg), mod) } BAD_EVAL_LOG = func(err error, mod string) error { return errMod(fmt.Errorf("failed to setup evaluation log: %w", err), mod) } BAD_ASSESSMENT_REQS = func(err error, mod string) error { return errMod(fmt.Errorf("failed to load assessment requirements from catalog: %w", err), mod) } BAD_CONFIG = func(err error, mod string) error { return errMod(fmt.Errorf("failed to setup config: %w", err), mod) } NO_MATCHING_CATALOGS = func(requested []string, available []string, mod string) error { return errMod(fmt.Errorf("no requested catalogs matched available suites. requested=%v available=%v", requested, available), mod) } )
Error functions that require parameters.
Functions ¶
This section is empty.
Types ¶
type ApplyFunc ¶ added in v1.7.0
type ApplyFunc func(interface{}) (interface{}, error)
ApplyFunc is a prepared function to apply a change.
type Change ¶
type Change struct {
// TargetName is the name or ID of the resource or configuration that is to be changed
TargetName string `yaml:"target-name"`
// Description is a human-readable description of the change
Description string `yaml:"description"`
// TargetObject is an optional representation of the object that is being changed
TargetObject interface{} `yaml:"target-object,omitempty"`
// Applied is true if the change was successfully applied at least once
Applied bool `yaml:"applied,omitempty"`
// Reverted is true if the change was successfully reverted and not applied again
Reverted bool `yaml:"reverted,omitempty"`
// Error is used if any error occurred during the change
Error error `yaml:"error,omitempty"`
// CorruptedState is true if something went wrong during apply or revert, indicating that the system may be in a bad state
CorruptedState bool `yaml:"bad-state,omitempty"`
// contains filtered or unexported fields
}
Change is a struct that contains the data and functions associated with a single change to a target resource.
func (*Change) AddFunctions ¶ added in v1.7.0
func (c *Change) AddFunctions(applyFunc ApplyFunc, revertFunc RevertFunc)
AddFunctions sets the apply and revert functions for a change.
type ChangeManager ¶ added in v1.7.0
type ChangeManager struct {
// Changes is a map of change names to Change objects, so that multiple changes can be tracked and reused.
Changes map[string]*Change `yaml:"changes"`
// Allowed must be set to true before any change can be applied.
Allowed bool `yaml:"allowed,omitempty"`
// CorruptedState is true if any change has failed to apply or revert, indicating that the system may be in a bad state.
CorruptedState bool `yaml:"bad-state,omitempty"`
}
ChangeManager manages changes that can be applied and reverted during evaluation.
func (*ChangeManager) AddChange ¶ added in v1.7.0
func (cm *ChangeManager) AddChange(changeName string, change Change)
AddChange adds a change to the change manager.
func (*ChangeManager) Allow ¶ added in v1.7.0
func (cm *ChangeManager) Allow()
Allow marks changes as allowed to be applied.
func (*ChangeManager) Apply ¶ added in v1.7.0
func (cm *ChangeManager) Apply(changeName string, targetName string, changeInput any) (success bool, target any)
Apply executes the prepared function for the change. It will not apply the change if it is not allowed, or if it has already been applied and not reverted.
func (*ChangeManager) Revert ¶ added in v1.7.0
func (cm *ChangeManager) Revert(changeName string)
Revert reverts a specific change by name.
func (*ChangeManager) RevertAll ¶ added in v1.7.0
func (cm *ChangeManager) RevertAll()
RevertAll reverts all changes managed by the change manager.
type DataLoader ¶ added in v1.0.1
DataLoader is a function type for loading plugin data from configuration.
type EvaluationOrchestrator ¶ added in v1.3.0
type EvaluationOrchestrator struct {
ServiceName string `yaml:"service-name"`
PluginName string `yaml:"plugin-name"`
PluginUri string `yaml:"plugin-uri"`
PluginVersion string `yaml:"plugin-version"`
Payload any `yaml:"payload,omitempty"`
Evaluation_Suites []*EvaluationSuite `yaml:"evaluation-suites"` // EvaluationSuite is a map of evaluations to their catalog names
// contains filtered or unexported fields
}
EvaluationOrchestrator gets the plugin in position to execute the specified evaluation suites.
func (*EvaluationOrchestrator) AddEvaluationSuite ¶ added in v1.3.0
func (v *EvaluationOrchestrator) AddEvaluationSuite(catalogId string, loader DataLoader, steps map[string][]gemara.AssessmentStep) error
AddEvaluationSuite adds an evaluation suite for the given catalog ID.
func (*EvaluationOrchestrator) AddEvaluationSuiteForAllCatalogs ¶ added in v1.22.0
func (v *EvaluationOrchestrator) AddEvaluationSuiteForAllCatalogs(loader DataLoader, steps map[string][]gemara.AssessmentStep) error
AddEvaluationSuiteForAllCatalogs registers the provided steps for every reference catalog that has been loaded via AddReferenceCatalogs. This allows plugin developers to define their step implementations once and have them automatically applied to all catalog versions.
func (*EvaluationOrchestrator) AddLoader ¶ added in v1.10.0
func (v *EvaluationOrchestrator) AddLoader(loader DataLoader)
AddLoader sets the data loader function for the orchestrator.
func (*EvaluationOrchestrator) AddReferenceCatalogs ¶ added in v1.10.0
func (v *EvaluationOrchestrator) AddReferenceCatalogs(dataDir string, files embed.FS) error
AddReferenceCatalogs loads reference catalogs from the embedded file system.
func (*EvaluationOrchestrator) AddRequiredVars ¶ added in v1.7.0
func (v *EvaluationOrchestrator) AddRequiredVars(vars []string)
AddRequiredVars sets the required configuration variables for the orchestrator.
func (*EvaluationOrchestrator) Mobilize ¶ added in v1.3.0
func (v *EvaluationOrchestrator) Mobilize() error
Mobilize initializes the orchestrator and executes all evaluation suites.
func (*EvaluationOrchestrator) WriteResults ¶ added in v1.3.0
func (v *EvaluationOrchestrator) WriteResults() error
WriteResults writes the evaluation results to files in the configured output format.
type EvaluationSuite ¶ added in v1.0.0
type EvaluationSuite struct {
Name string // Name is the name of the suite
Result gemara.Result // Result is Passed if all evaluations in the suite passed
CatalogId string `yaml:"catalog-id"` // CatalogId associates this suite with a catalog
StartTime string `yaml:"start-time"` // StartTime is the time the plugin started
EndTime string `yaml:"end-time"` // EndTime is the time the plugin ended
CorruptedState bool `yaml:"corrupted-state"` // CorruptedState is true if any testSet failed to revert at the end of the evaluation
EvaluationLog gemara.EvaluationLog `yaml:"control-evaluations"` // EvaluationLog is a slice of evaluations to be executed
// contains filtered or unexported fields
}
EvaluationSuite contains the results of all EvaluationLog executions. Exported fields will be used in the final YAML or JSON output documents.
func (*EvaluationSuite) AddChangeManager ¶ added in v1.7.0
func (e *EvaluationSuite) AddChangeManager(cm *ChangeManager)
AddChangeManager sets up the change manager for the evaluation suite.
func (*EvaluationSuite) Evaluate ¶ added in v1.0.0
func (e *EvaluationSuite) Evaluate(serviceName string) error
Evaluate executes a list of EvaluationLog provided by a Plugin and customized by user config. Name is an arbitrary string that will be used to identify the EvaluationSuite.
func (*EvaluationSuite) GetAssessmentRequirements ¶ added in v1.7.0
func (e *EvaluationSuite) GetAssessmentRequirements() (map[string]*gemara.AssessmentRequirement, error)
GetAssessmentRequirements retrieves all assessment requirements from the catalog.
type RevertFunc ¶ added in v1.7.0
type RevertFunc func(interface{}) error
RevertFunc is a prepared function to revert a change after it has been applied.
type TestSet ¶
type TestSet func() (result gemara.ControlEvaluation)
TestSet is a function type that returns a control evaluation result.