engine

Documentation

Overview

Package engine loads and evaluates control packs.

Index

• Constants
• func AffectedControlIDs(packs []Pack, paths, scopes []string) []string
• func ValidateFile(path string) error
• type Availability
• type CategoryScore
• type ClassificationSummary
• type Control
• type ControlOverride
• type ExceptionBinding
• type ExceptionEvidence
• type ExceptionInput
• type Finding
• type Input
• type Match
• type Metadata
• type NamespaceInput
• type Pack
  • func LoadBuiltins() ([]Pack, error)
  • func LoadPacks(paths []string) ([]Pack, error)
• type Provenance
  • func ProvenanceFor(packs []Pack) []Provenance
• type Remediation
• type ReportContext
• type ResourceInput
• type ResourceRef
• type Result
  • func ApplyExceptions(result Result, exceptions []ExceptionInput, bindings []ExceptionBinding) Result
  • func Evaluate(packs []Pack, input Input) (Result, error)
• type Source
• type WorkloadContext
• type WorkloadInput

Constants

const (
	APIVersion = "openmeshguard.io/v1alpha1"
	Kind       = "ControlPack"
)

Functions

func AffectedControlIDs

func AffectedControlIDs(packs []Pack, paths, scopes []string) []string

AffectedControlIDs derives permission impact from the controls loaded for the current scan. Paths identify evidence that may be unavailable; scopes identify target sets that may be incomplete because their backing resources could not be listed.

func ValidateFile

func ValidateFile(path string) error

ValidateFile validates one user control pack without loading cluster state.

Types

type Availability

type Availability struct {
	Available bool
	Reason    string
}

Availability overrides the engine's default availability inference for a dotted path. It is how producers distinguish a known false/empty value from a field whose evidence has not been collected yet.

type CategoryScore

type CategoryScore struct {
	Category  string
	Grade     string
	PassRate  *float64
	Evaluated int
	Unknown   int
}

type ClassificationSummary

type ClassificationSummary struct {
	NamespacesClassified   int
	NamespacesUnclassified int
	ByEnvironment          map[string]int
}

type Control

type Control struct {
	ID            string      `yaml:"id"`
	Title         string      `yaml:"title"`
	Category      string      `yaml:"category"`
	Severity      string      `yaml:"severity"`
	EvidenceType  string      `yaml:"evidenceType"`
	Scope         string      `yaml:"scope"`
	Environments  []string    `yaml:"environments,omitempty"`
	Requires      []string    `yaml:"requires"`
	Applicability string      `yaml:"applicability"`
	Expression    string      `yaml:"expression"`
	Message       string      `yaml:"message"`
	Remediation   Remediation `yaml:"remediation"`
	Frameworks    []string    `yaml:"frameworks,omitempty"`
	Match         Match       `yaml:"match,omitempty"`
	// contains filtered or unexported fields
}

type ControlOverride

type ControlOverride struct {
	Environments          *[]string
	SeverityByEnvironment map[string]string
}

type ExceptionBinding

type ExceptionBinding struct {
	Resource    ResourceRef
	ExceptionID string
	Owner       string
	OwnerKnown  bool
}

type ExceptionEvidence

type ExceptionEvidence struct {
	ID        string
	Expired   bool
	ExpiresAt time.Time
	Approver  string
	Ticket    string
}

type ExceptionInput

type ExceptionInput struct {
	ID         string
	Owner      string
	ControlIDs []string
	Valid      bool
	Expired    bool
	ExpiresAt  time.Time
	Approver   string
	Ticket     string
}

type Finding

type Finding struct {
	ID              string
	ControlID       string
	Title           string
	Severity        string
	EvidenceType    string
	Status          string
	Confidence      string
	DataPlaneMode   string
	EvidenceSources []string
	Resources       []ResourceRef
	ResolutionChain []resolver.Step
	Reasoning       string
	Remediation     Remediation
	Exception       *ExceptionEvidence
	UnknownReason   string
}

type Input

type Input struct {
	Workloads  []WorkloadInput
	Namespaces []NamespaceInput
	// NamespaceTargetsComplete prevents namespace-scope evaluation from
	// deriving additional targets from workload context. The scan path sets it
	// after selecting mesh and unknown-enrollment namespaces.
	NamespaceTargetsComplete bool
	Resources                []ResourceInput
	Inventory                map[string]any
	InventoryAvailability    map[string]Availability
	Params                   map[string]any
	EnvironmentParams        map[string]map[string]any
	ControlOverrides         map[string]ControlOverride
}

Input is the complete evaluation input. Inventory and Params are dynamic maps because their contract-backed shapes expand in later milestones.

type Match

type Match struct {
	APIGroups []string `yaml:"apiGroups,omitempty"`
	Kinds     []string `yaml:"kinds,omitempty"`
}

type Metadata

type Metadata struct {
	Name    string `yaml:"name"`
	Version string `yaml:"version"`
}

type NamespaceInput

type NamespaceInput struct {
	Name                  string
	Labels                map[string]string
	Environment           string
	EnvironmentConfidence string
	EnvironmentKnown      bool
	MeshEnrollment        string
	EvidenceSources       []string
	Availability          map[string]Availability
}

NamespaceInput is the normalized namespace view exposed to namespace and workload CEL environments.

type Pack

type Pack struct {
	APIVersion string         `yaml:"apiVersion"`
	Kind       string         `yaml:"kind"`
	Metadata   Metadata       `yaml:"metadata"`
	Params     map[string]any `yaml:"params,omitempty"`
	Controls   []Control      `yaml:"controls"`

	File   string `yaml:"-"`
	Source Source `yaml:"-"`
}

Pack is a validated, compiled control pack.

func LoadBuiltins

func LoadBuiltins() ([]Pack, error)

LoadBuiltins loads every embedded .yaml control pack.

func LoadPacks

func LoadPacks(paths []string) ([]Pack, error)

LoadPacks loads all embedded built-ins plus repeatable user-supplied paths, validates the complete set, and rejects duplicate control IDs.

type Provenance

type Provenance struct {
	Name    string
	Version string
	Source  string
}

func ProvenanceFor

func ProvenanceFor(packs []Pack) []Provenance

type Remediation

type Remediation struct {
	Guidance              string `yaml:"guidance"`
	SuggestedYAMLTemplate string `yaml:"suggestedYAMLTemplate,omitempty"`
	SuggestedYAML         string `yaml:"-"`
}

type ReportContext

type ReportContext struct {
	EnvironmentInference bool
	ScanConfig           bool
	OwnershipImport      bool
	Exceptions           bool
	Classification       ClassificationSummary
	Workloads            []WorkloadContext
}

type ResourceInput

type ResourceInput struct {
	APIVersion      string
	Kind            string
	Namespace       string
	Name            string
	Environment     string
	Fields          map[string]any
	EvidenceSources []string
	Availability    map[string]Availability
}

ResourceInput is the normalized resource view for resource-scoped controls.

type ResourceRef

type ResourceRef struct {
	APIVersion string
	Kind       string
	Namespace  string
	Name       string
}

type Result

type Result struct {
	Findings []Finding
	Scores   []CategoryScore
	Context  ReportContext
}

func ApplyExceptions

func ApplyExceptions(result Result, exceptions []ExceptionInput, bindings []ExceptionBinding) Result

ApplyExceptions annotates already-evaluated findings. It never removes a finding, changes its severity, or exposes exception state to control CEL.

func Evaluate

func Evaluate(packs []Pack, input Input) (Result, error)

Evaluate applies every validated control to its scope targets. Evidence read by applicability is checked before applicability executes; declared evidence for the expression is checked after a target is known to apply. This preserves not-applicable as a resolved state without allowing unavailable evidence to exempt a target or reach CEL evaluation.

type Source

type Source string

const (
	SourceBuiltin Source = "builtin"
	SourceUser    Source = "user"
)

type WorkloadContext

type WorkloadContext struct {
	Ref                   resolver.WorkloadRef
	Environment           string
	EnvironmentConfidence string
	EnvironmentKnown      bool
	Owner                 string
	OwnerKnown            bool
	AppID                 string
	AppIDKnown            bool
}

type WorkloadInput

type WorkloadInput struct {
	Posture               resolver.WorkloadResult
	Namespace             NamespaceInput
	Environment           string
	EnvironmentConfidence string
	EnvironmentKnown      bool
	Owner                 string
	OwnerKnown            bool
	AppID                 string
	AppIDKnown            bool
	EvidenceSources       []string
	Verified              map[string]any
	Availability          map[string]Availability
}

WorkloadInput joins one resolver output to its namespace context and any producer-supplied availability facts.