pluginkit

package
v1.24.0 Latest Latest
Warning

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

Go to latest
Published: Apr 30, 2026 License: Apache-2.0 Imports: 15 Imported by: 3

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.

Each error factory wraps one of the two category sentinels below so ExitCodeFor can classify it into the right exit code via errors.Is.

Index

Constants

This section is empty.

Variables

View Source
var (
	CORRUPTION_FOUND = func(mod string) error {
		return wrap(ErrRuntime, "target state may be corrupted! Halting to prevent futher damage. See logs for more information", mod)
	}
	NO_EVALUATION_SUITES = func(mod string) error {
		return wrap(ErrDevBug, "no control evaluations provided by the plugin", mod)
	}
	EVAL_NAME_MISSING = func(mod string) error {
		return wrap(ErrDevBug, "evaluationSuite name must not be empty", mod)
	}
	CONFIG_NOT_INITIALIZED = func(mod string) error {
		return wrap(ErrDevBug, "configuration not initialized", mod)
	}
	NO_ASSESSMENT_STEPS_PROVIDED = func(mod string) error {
		return wrap(ErrDevBug, "assessment steps not provided", mod)
	}
	NO_ASSESSMENT_REQS_PROVIDED = func(mod string) error {
		return wrap(ErrDevBug, "assessment requirements not provided", mod)
	}
	EVAL_SUITE_CRASHED = func(mod string) error {
		return wrap(ErrDevBug, "evaluation suite crashed", mod)
	}
)

Error functions that require no parameters.

View Source
var (
	EVALUATION_ORCHESTRATOR_NAMES_NOT_SET = func(serviceName, pluginName string, mod string) error {
		return wrap(ErrDevBug, fmt.Sprintf("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 wrap(ErrRuntime, fmt.Sprintf("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 wrap(ErrRuntime, fmt.Sprintf("failed to load payload for %s: %s", pluginName, err), mod)
	}
	BAD_CATALOG = func(pluginName string, errMsg string, mod string) error {
		return wrap(ErrDevBug, fmt.Sprintf("malformed data in catalog for %s: %s", pluginName, errMsg), mod)
	}
	BAD_EVAL_LOG = func(err error, mod string) error {
		return wrap(ErrDevBug, fmt.Sprintf("failed to setup evaluation log: %s", err), mod)
	}
	BAD_ASSESSMENT_REQS = func(err error, mod string) error {
		return wrap(ErrDevBug, fmt.Sprintf("failed to load assessment requirements from catalog: %s", err), mod)
	}
	BAD_CONFIG = func(err error, mod string) error {
		return wrap(ErrRuntime, fmt.Sprintf("failed to setup config: %s", err), mod)
	}
	NO_MATCHING_CATALOGS = func(requested []string, available []string, mod string) error {
		return wrap(ErrDevBug, fmt.Sprintf("no requested catalogs matched available suites. requested=%v available=%v", requested, available), mod)
	}
)

Error functions that require parameters.

View Source
var ErrDevBug = errors.New("privateer plugin development error")

ErrDevBug classifies SDK misuse or malformed plugin data (missing catalogs, unset names, missing assessment steps). Maps to BadUsage.

View Source
var ErrRuntime = errors.New("privateer plugin runtime error")

ErrRuntime classifies failures during plugin execution that aren't the plugin author's fault (loader, write, RPC, corruption). Maps to InternalError.

Functions

func ExitCodeFor added in v1.24.0

func ExitCodeFor(orch *EvaluationOrchestrator, mobilizeErr error) int

ExitCodeFor maps the outcome of EvaluationOrchestrator.Mobilize into a canonical privateer exit code. Plugin authors call this from Start:

func (p *Plugin) Start() (int, error) {
    err := p.orchestrator.Mobilize()
    return pluginkit.ExitCodeFor(p.orchestrator, err), err
}

A non-nil error wrapping ErrRuntime → InternalError; ErrDevBug → BadUsage; any other non-nil error → InternalError. With nil error, suite results containing Failed/NeedsReview/Unknown → TestFail; otherwise TestPass.

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

type DataLoader func(*config.Config) (any, error)

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.

Jump to

Keyboard shortcuts

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