evaluator

package
v0.8.32 Latest Latest
Warning

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

 Go to latest Published: Sep 30, 2025 License: Apache-2.0 Imports: 26 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ExtractStringFromMetadata 

func ExtractStringFromMetadata(result Result, key string) string

ExtractStringFromMetadata returns the string value from the result metadata at the given key.

func LegacyIsResultIncluded added in v0.8.2 

func LegacyIsResultIncluded(result Result, target string, missingIncludes map[string]bool, include *Criteria, exclude *Criteria) bool

LegacyIsResultIncluded determines whether a result should be included based on include/exclude criteria and scoring logic. This is the legacy filtering function.

func LegacyMakeMatchers added in v0.8.2 

func LegacyMakeMatchers(result Result) []string

LegacyMakeMatchers returns the possible matching strings for the result. This is the legacy matcher function.

func LegacyScore added in v0.8.2 

func LegacyScore(name string) int

LegacyScore computes and returns the specificity of the given name. The scoring guidelines are:

  1. If the name starts with "@" the returned score is exactly 10, e.g. "@collection". No further processing is done.
  2. Add 1 if the name covers everything, i.e. "*"
  3. Add 10 if the name specifies a package name, e.g. "pkg", "pkg.", "pkg.*", or "pkg.rule", and an additional 10 based on the namespace depth of the pkg, e.g. "a.pkg.rule" adds 10 more, "a.b.pkg.rule" adds 20, etc
  4. Add 100 if a term is used, e.g. "*:term", "pkg:term" or "pkg.rule:term"
  5. Add 100 if a rule is used, e.g. "pkg.rule", "pkg.rule:term"

The score is cumulative. If a name is covered by multiple items in the guidelines, they are added together. For example, "pkg.rule:term" scores at 210. This is the legacy scoring function.

func LegacyScoreMatches added in v0.8.2 

func LegacyScoreMatches(needles, haystack []string, toBePruned map[string]bool) int

LegacyScoreMatches returns the combined score for every match between needles and haystack. 'toBePruned' contains items that will be removed (pruned) from this map if a match is found. This is the legacy scoring function.

Types

type ConfigProvider 

type ConfigProvider interface {
	EffectiveTime() time.Time
	SigstoreOpts() (policy.SigstoreOpts, error)
	Spec() ecc.EnterpriseContractPolicySpec
}

ConfigProvider is a subset of the policy.Policy interface. Its purpose is to codify which parts of Policy are actually used and to make it easier to use mock in tests.

type Criteria 

type Criteria struct {
	// contains filtered or unexported fields
}

contains include/exclude items digestItems stores include/exclude items that are specific with an imageRef - the imageRef is the key, value is the policy to include/exclude. defaultItems are include/exclude items without an imageRef

type Data 

type Data map[string]any

type DefaultFilterFactory added in v0.7.127 

type DefaultFilterFactory struct{}

DefaultFilterFactory creates filters based on the source configuration. It handles two main filtering mechanisms: 1. Pipeline intention filtering - based on rule metadata 2. Include list filtering - based on explicit package/collection names

func (*DefaultFilterFactory) CreateFilters added in v0.7.127 

func (f *DefaultFilterFactory) CreateFilters(source ecc.Source) []RuleFilter

CreateFilters builds a list of filters based on the source configuration.

The filtering logic follows these rules: 1. Pipeline Intention Filtering:

  • When pipeline_intention is set in ruleData: only include packages with rules that have matching pipeline_intention metadata
  • When pipeline_intention is NOT set in ruleData: only include packages with rules that have NO pipeline_intention metadata (general-purpose rules)

2. Include List Filtering:

  • When includes are specified: only include packages that match the include criteria
  • Supports @collection, package names, and package.rule patterns

3. Combined Logic:

  • All filters are applied with AND logic - a package must pass ALL filters
  • This allows fine-grained control over which rules are evaluated

type ECPolicyResolver added in v0.8.2 

type ECPolicyResolver struct {
	// contains filtered or unexported fields
}

ECPolicyResolver implements PolicyResolver using the existing filtering logic and scoring system.

func (*ECPolicyResolver) Excludes added in v0.8.2 

func (r *ECPolicyResolver) Excludes() *Criteria

Excludes returns the exclude criteria used by this policy resolver

func (*ECPolicyResolver) Includes added in v0.8.2 

func (r *ECPolicyResolver) Includes() *Criteria

Includes returns the include criteria used by this policy resolver

func (*ECPolicyResolver) ResolvePolicy added in v0.8.2 

func (r *ECPolicyResolver) ResolvePolicy(rules policyRules, target string) PolicyResolutionResult

ResolvePolicy determines which rules and packages are included/excluded based on the policy configuration and available rules.

END RESULT: Returns a comprehensive PolicyResolutionResult containing:

1. Rule-Level Decisions:

  • IncludedRules: Map of rule IDs that should be evaluated (e.g., "package.rule")
  • ExcludedRules: Map of rule IDs that are explicitly excluded
  • Explanations: Detailed reasons for each rule's inclusion/exclusion decision

2. Package-Level Decisions:

  • IncludedPackages: Map of package names that contain included rules
  • ExcludedPackages: Map of package names that contain only excluded rules
  • Explanations: Reasons for package-level decisions

3. Missing Includes Tracking:

  • MissingIncludes: Include criteria that didn't match any rules (for validation)

This result can be used to: - Filter which rules are actually evaluated by conftest - Determine which packages should be loaded for evaluation - Provide detailed explanations for policy decisions - Validate that all include criteria were matched - Generate comprehensive policy reports

type EvaluationTarget 

type EvaluationTarget struct {
	Inputs []string
	Target string
}

type Evaluator 

type Evaluator interface {
	Evaluate(ctx context.Context, target EvaluationTarget) ([]Outcome, error)

	// Destroy performs any cleanup needed
	Destroy()

	// CapabilitiesPath returns the path to the file where capabilities are defined
	CapabilitiesPath() string
}

func NewConftestEvaluator 

func NewConftestEvaluator(ctx context.Context, policySources []source.PolicySource, p ConfigProvider, source ecc.Source) (Evaluator, error)

NewConftestEvaluator returns initialized conftestEvaluator implementing Evaluator interface

func NewConftestEvaluatorWithFilterType added in v0.8.18 

func NewConftestEvaluatorWithFilterType(ctx context.Context, policySources []source.PolicySource, p ConfigProvider, source ecc.Source, filterType string) (Evaluator, error)

NewConftestEvaluatorWithFilterType returns initialized conftestEvaluator with a specific filter type

func NewConftestEvaluatorWithNamespace 

func NewConftestEvaluatorWithNamespace(ctx context.Context, policySources []source.PolicySource, p ConfigProvider, source ecc.Source, namespace []string) (Evaluator, error)

set the policy namespace

func NewConftestEvaluatorWithNamespaceAndFilterType added in v0.8.18 

func NewConftestEvaluatorWithNamespaceAndFilterType(
	ctx context.Context,
	policySources []source.PolicySource,
	p ConfigProvider,
	source ecc.Source,
	namespace []string,
	filterType string,
) (Evaluator, error)

NewConftestEvaluatorWithNamespaceAndFilterType returns initialized conftestEvaluator with namespace and filter type

func NewConftestEvaluatorWithPostEvaluationFilter added in v0.8.2 

func NewConftestEvaluatorWithPostEvaluationFilter(ctx context.Context, policySources []source.PolicySource, p ConfigProvider, source ecc.Source, postEvaluationFilter PostEvaluationFilter) (Evaluator, error)

NewConftestEvaluatorWithPostEvaluationFilter returns initialized conftestEvaluator with a custom post-evaluation filter

func NewOPAEvaluator 

func NewOPAEvaluator() (Evaluator, error)

type FilterFactory added in v0.7.127 

type FilterFactory interface {
	CreateFilters(source ecc.Source) []RuleFilter
}

FilterFactory builds a slice of filters for a given `ecc.Source`.

Multiple filters can be applied simultaneously using AND logic - all filters must approve a package for it to be included in the evaluation set.

func NewDefaultFilterFactory added in v0.7.127 

func NewDefaultFilterFactory() FilterFactory

func NewIncludeFilterFactory added in v0.7.127 

func NewIncludeFilterFactory() FilterFactory

type IncludeExcludePolicyResolver added in v0.8.2 

type IncludeExcludePolicyResolver struct {
	// contains filtered or unexported fields
}

IncludeExcludePolicyResolver implements PolicyResolver using the existing filtering logic and scoring system, but ignores pipeline intention filtering.

func (*IncludeExcludePolicyResolver) Excludes added in v0.8.2 

func (r *IncludeExcludePolicyResolver) Excludes() *Criteria

Excludes returns the exclude criteria used by this policy resolver

func (*IncludeExcludePolicyResolver) Includes added in v0.8.2 

func (r *IncludeExcludePolicyResolver) Includes() *Criteria

Includes returns the include criteria used by this policy resolver

func (*IncludeExcludePolicyResolver) ResolvePolicy added in v0.8.2 

func (r *IncludeExcludePolicyResolver) ResolvePolicy(rules policyRules, target string) PolicyResolutionResult

ResolvePolicy determines which rules and packages are included/excluded based on the policy configuration and available rules, ignoring pipeline intention filtering.

type IncludeFilterFactory added in v0.7.127 

type IncludeFilterFactory struct{}

func (*IncludeFilterFactory) CreateFilters added in v0.7.127 

func (f *IncludeFilterFactory) CreateFilters(source ecc.Source) []RuleFilter

CreateFilters builds a list of filters based on the source configuration.

The filtering logic follows these rules: 1. Pipeline Intention Filtering:

  • When pipeline_intention is set in ruleData: only include packages with rules that have matching pipeline_intention metadata
  • When pipeline_intention is NOT set in ruleData: only include packages with rules that have NO pipeline_intention metadata (general-purpose rules)

2. Include List Filtering:

  • When includes are specified: only include packages that match the include criteria
  • Supports @collection, package names, and package.rule patterns

3. Combined Logic:

  • All filters are applied with AND logic - a package must pass ALL filters
  • This allows fine-grained control over which rules are evaluated

type IncludeListFilter added in v0.7.127 

type IncludeListFilter struct {
	// contains filtered or unexported fields
}

IncludeListFilter filters packages based on explicit include criteria.

This filter provides fine-grained control over which packages are evaluated by allowing explicit specification of packages, collections, or individual rules.

Supported patterns: - "@collection" - includes any package with rules that belong to the specified collection - "package" - includes the entire package - "package.rule" - includes the package containing the specified rule

Examples: - ["@security"] - includes packages with rules in the "security" collection - ["cve"] - includes the "cve" package - ["release.security_check"] - includes the "release" package (which contains the rule)

func (*IncludeListFilter) Include added in v0.7.127 

func (f *IncludeListFilter) Include(pkg string, rules []rule.Info) bool

Include determines whether a package should be included based on the include list criteria.

The function checks if the package or any of its rules match the include criteria. If any rule in the package matches, the entire package is included.

type LegacyPostEvaluationFilter added in v0.8.2 

type LegacyPostEvaluationFilter struct {
	// contains filtered or unexported fields
}

LegacyPostEvaluationFilter implements the PostEvaluationFilter interface using only the include/exclude criteria, matching the legacy behavior.

func (*LegacyPostEvaluationFilter) CategorizeResults added in v0.8.2 

func (f *LegacyPostEvaluationFilter) CategorizeResults(
	filteredResults []Result,
	originalResult Outcome,
	effectiveTime time.Time,
) (warnings []Result, failures []Result, exceptions []Result, skipped []Result)

CategorizeResults implements the PostEvaluationFilter interface for legacy compatibility. This method provides a simple categorization that preserves the original result types.

func (*LegacyPostEvaluationFilter) FilterResults added in v0.8.2 

func (f *LegacyPostEvaluationFilter) FilterResults(
	results []Result,
	rules policyRules,
	target string,
	missingIncludes map[string]bool,
	effectiveTime time.Time,
) ([]Result, map[string]bool)

FilterResults processes all result types and returns the filtered results along with updated missing includes tracking.

type NamespaceFilter added in v0.7.127 

type NamespaceFilter struct {
	// contains filtered or unexported fields
}

NamespaceFilter applies multiple filters using AND logic.

This filter combines multiple RuleFilter instances and only includes packages that pass ALL filters. This allows for complex filtering scenarios where multiple criteria must be satisfied.

Example: Pipeline intention + Include list - Pipeline intention filter: only packages with matching pipeline_intention - Include list filter: only packages in the include list - Result: only packages that satisfy BOTH conditions

func NewNamespaceFilter added in v0.7.127 

func NewNamespaceFilter(filters ...RuleFilter) *NamespaceFilter

func (*NamespaceFilter) Filter added in v0.7.127 

func (nf *NamespaceFilter) Filter(rules policyRules) []string

Filter applies all filters to the given rules and returns the list of packages that pass all filter criteria.

The filtering process: 1. Groups rules by package (namespace) 2. For each package, applies all filters in sequence 3. Only includes packages that pass ALL filters (AND logic) 4. Returns the list of approved package names

This ensures that only the appropriate rules are evaluated based on the current configuration and context.

type Outcome 

type Outcome struct {
	FileName   string   `json:"filename"`
	Namespace  string   `json:"namespace"`
	Successes  []Result `json:"successes,omitempty"`
	Skipped    []Result `json:"skipped,omitempty"`
	Warnings   []Result `json:"warnings,omitempty"`
	Failures   []Result `json:"failures,omitempty"`
	Exceptions []Result `json:"exceptions,omitempty"`
}

type PipelineIntentionFilter added in v0.7.127 

type PipelineIntentionFilter struct {
	// contains filtered or unexported fields
}

PipelineIntentionFilter filters packages based on pipeline_intention metadata.

This filter ensures that only rules appropriate for the current pipeline context are evaluated. It works by examining the pipeline_intention metadata in each rule and comparing it against the configured pipeline_intention values.

Behavior: - When targetIntentions is empty (no pipeline_intention configured):

  • Only includes packages with rules that have NO pipeline_intention metadata
  • This allows general-purpose rules to run in default contexts

- When targetIntentions is set (pipeline_intention configured):

  • Only includes packages with rules that have MATCHING pipeline_intention metadata
  • This ensures only pipeline-specific rules are evaluated

Examples: - Config: pipeline_intention: ["release"]

  • Rule with pipeline_intention: ["release", "production"] → INCLUDED
  • Rule with pipeline_intention: ["staging"] → EXCLUDED
  • Rule with no pipeline_intention metadata → EXCLUDED

- Config: no pipeline_intention set

  • Rule with pipeline_intention: ["release"] → EXCLUDED
  • Rule with no pipeline_intention metadata → INCLUDED

func (*PipelineIntentionFilter) Include added in v0.7.127 

func (f *PipelineIntentionFilter) Include(_ string, rules []rule.Info) bool

Include determines whether a package should be included based on pipeline_intention metadata.

The function examines all rules in the package to determine if any have appropriate pipeline_intention metadata for the current configuration.

type PolicyResolutionResult added in v0.8.2 

type PolicyResolutionResult struct {
	// IncludedRules contains all rule IDs that are included in the policy
	IncludedRules map[string]bool
	// ExcludedRules contains all rule IDs that are explicitly excluded
	ExcludedRules map[string]bool
	// IncludedPackages contains all package names that are included
	IncludedPackages map[string]bool
	// MissingIncludes contains include criteria that didn't match any rules
	MissingIncludes map[string]bool
	// Explanations provides reasons for why rules/packages were included/excluded
	Explanations map[string]string
}

PolicyResolutionResult contains the comprehensive results of policy resolution.

func GetECPolicyResolution added in v0.8.2 

func GetECPolicyResolution(source ecc.Source, p ConfigProvider, rules policyRules, target string) PolicyResolutionResult

GetECPolicyResolution is a convenience function that creates a PolicyResolver and resolves the policy for the given rules and target.

This function provides a simple way to get comprehensive policy resolution results including all included/excluded rules and packages, with explanations.

func GetIncludeExcludePolicyResolution added in v0.8.2 

func GetIncludeExcludePolicyResolution(source ecc.Source, p ConfigProvider, rules policyRules, target string) PolicyResolutionResult

GetIncludeExcludePolicyResolution is a convenience function that creates a PolicyResolver that ignores pipeline intention filtering and resolves the policy for the given rules and target.

This function provides a simple way to get policy resolution results including all included/excluded rules and packages, with explanations, but without pipeline intention filtering.

func NewPolicyResolutionResult added in v0.8.2 

func NewPolicyResolutionResult() PolicyResolutionResult

NewPolicyResolutionResult creates a new PolicyResolutionResult with initialized maps

type PolicyResolver added in v0.8.2 

type PolicyResolver interface {
	// ResolvePolicy determines which rules and packages are included/excluded
	// based on the policy configuration and available rules.
	ResolvePolicy(rules policyRules, target string) PolicyResolutionResult

	// Includes returns the include criteria used by this policy resolver
	Includes() *Criteria

	// Excludes returns the exclude criteria used by this policy resolver
	Excludes() *Criteria
}

PolicyResolver provides comprehensive policy resolution capabilities. It can determine which rules and packages are included/excluded based on the policy configuration, taking into account all criteria including includes, excludes, collections, pipeline intentions, and volatile config.

func NewECPolicyResolver added in v0.8.2 

func NewECPolicyResolver(source ecc.Source, p ConfigProvider) PolicyResolver

NewECPolicyResolver creates a new PolicyResolver that uses the existing filtering and scoring logic.

func NewIncludeExcludePolicyResolver added in v0.8.2 

func NewIncludeExcludePolicyResolver(source ecc.Source, p ConfigProvider) PolicyResolver

NewIncludeExcludePolicyResolver creates a new PolicyResolver that uses the existing filtering and scoring logic but ignores pipeline intention filtering.

Example usage: 

source := ecc.Source{
    RuleData: &extv1.JSON{Raw: json.RawMessage(`{"pipeline_intention":["build"]}`)},
    Config: &ecc.SourceConfig{Include: []string{"*"}},
}
config := &simpleConfigProvider{effectiveTime: time.Now()}
resolver := NewIncludeExcludePolicyResolver(source, config)
result := resolver.ResolvePolicy(rules, "test-target")
// result will include all rules regardless of pipeline intention

type PostEvaluationFilter added in v0.8.2 

type PostEvaluationFilter interface {
	// FilterResults processes all result types and returns the filtered results
	// along with updated missing includes tracking.
	FilterResults(
		results []Result,
		rules policyRules,
		target string,
		missingIncludes map[string]bool,
		effectiveTime time.Time,
	) ([]Result, map[string]bool)

	// CategorizeResults takes filtered results and categorizes them by type
	// (warnings, failures, exceptions, skipped) with appropriate severity logic.
	CategorizeResults(
		filteredResults []Result,
		originalResult Outcome,
		effectiveTime time.Time,
	) (warnings []Result, failures []Result, exceptions []Result, skipped []Result)
}

PostEvaluationFilter decides whether individual results (warnings, failures, exceptions, skipped, successes) should be included in the final output.

This filtering happens after all rules have been executed by conftest, allowing for fine-grained control over which results are reported. It handles include/exclude criteria, severity promotion/demotion, effective time filtering, and success computation.

func NewLegacyPostEvaluationFilter added in v0.8.2 

func NewLegacyPostEvaluationFilter(source ecc.Source, p ConfigProvider) PostEvaluationFilter

NewLegacyPostEvaluationFilter creates a new legacy-style post-evaluation filter.

func NewUnifiedPostEvaluationFilter added in v0.8.2 

func NewUnifiedPostEvaluationFilter(policyResolver PolicyResolver) PostEvaluationFilter

NewUnifiedPostEvaluationFilter creates a new unified post-evaluation filter that uses the same PolicyResolver for consistent filtering logic.

type Result 

type Result struct {
	Message  string                 `json:"msg"`
	Metadata map[string]interface{} `json:"metadata,omitempty"`
	Outputs  []string               `json:"outputs,omitempty"`
}

type RuleFilter added in v0.7.127 

type RuleFilter interface {
	Include(pkg string, rules []rule.Info) bool
}

RuleFilter decides whether an entire package (namespace) should be included in the evaluation set.

The filtering system works at the package level - if any rule in a package matches the filter criteria, the entire package is included for evaluation. This ensures that related rules within the same package are evaluated together.

func NewIncludeListFilter added in v0.7.127 

func NewIncludeListFilter(entries []string) RuleFilter

func NewPipelineIntentionFilter added in v0.7.127 

func NewPipelineIntentionFilter(target []string) RuleFilter

type UnifiedPostEvaluationFilter added in v0.8.2 

type UnifiedPostEvaluationFilter struct {
	// contains filtered or unexported fields
}

UnifiedPostEvaluationFilter implements the PostEvaluationFilter interface using the unified policy resolution approach. This filter handles all aspects of post-evaluation filtering including result categorization and severity logic.

func (*UnifiedPostEvaluationFilter) CategorizeResults added in v0.8.2 

func (f *UnifiedPostEvaluationFilter) CategorizeResults(
	filteredResults []Result,
	originalResult Outcome,
	effectiveTime time.Time,
) (warnings []Result, failures []Result, exceptions []Result, skipped []Result)

CategorizeResults takes filtered results and categorizes them by type (warnings, failures, exceptions, skipped) with appropriate severity logic.

func (*UnifiedPostEvaluationFilter) FilterResults added in v0.8.2 

func (f *UnifiedPostEvaluationFilter) FilterResults(
	results []Result,
	rules policyRules,
	target string,
	missingIncludes map[string]bool,
	effectiveTime time.Time,
) ([]Result, map[string]bool)

FilterResults processes all result types and returns the filtered results along with updated missing includes tracking. This method handles: 1. Policy-based filtering using the unified PolicyResolver 2. Result categorization (warnings, failures, exceptions, skipped) 3. Severity logic and effective time filtering 4. Missing includes tracking

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.