policyeval

package
v0.20.0 Latest Latest
Warning

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

Go to latest
Published: Oct 1, 2026 License: AGPL-3.0 Imports: 17 Imported by: 0

Documentation

Overview

Package policyeval evaluates compliance_framework Rego policies. It is the single implementation shared by the agent's policy-manager and the API's playback endpoint, so a result from one means the same as a result from the other.

Index

Constants

View Source
const (
	ErrCodeTimeout    = "eval_timeout"
	ErrCodeNoPolicies = "no_policies"
	ErrCodeEval       = "eval_error"
	ErrCodeModuleName = "invalid_module_name"
)

Error codes returned in EvalError.Code besides OPA's own (rego_parse_error, rego_compile_error, rego_type_error, eval_conflict_error, eval_builtin_error, ...).

View Source
const (
	StatusSatisfied    = "satisfied"
	StatusNotSatisfied = "not-satisfied"
	StatusSkipped      = "skipped"
)
View Source
const MaxPrints = 1000

MaxPrints caps how many print() lines one evaluation returns.

View Source
const PolicyModuleName = "policy.rego"

PolicyModuleName is the module name the request's policy source is stored under.

Variables

View Source
var DeniedBuiltins = []string{
	"http.send",
	"net.lookup_ip_addr",
	"opa.runtime",
}

DeniedBuiltins are the builtins that reach outside the evaluator: the network or the host process. Policies that call one fail to compile under SandboxCapabilities.

Functions

func MergeData added in v0.20.0

func MergeData(base, overlay map[string]any) map[string]any

MergeData deep-merges overlay into a copy of base: nested objects are merged key by key, and any other value in overlay replaces the one in base. This is how the agent layers its configured policy data over a bundle's own data documents.

func SandboxCapabilities

func SandboxCapabilities() *ast.Capabilities

SandboxCapabilities returns this OPA version's capabilities with DeniedBuiltins removed. Each call returns a fresh copy that the caller may modify.

func Status

func Status(result Result) string

Status applies the agent's GenerateResults rule: a non-empty skip_reason means the result produces no evidence; otherwise no violations is satisfied and any violation is not satisfied.

Types

type ErrorResponse

type ErrorResponse struct {
	Errors []EvalError `json:"errors"`
}

ErrorResponse is the 422 body of POST /api/playback/evaluate.

type EvalError

type EvalError struct {
	Code    string `json:"code"`
	Message string `json:"message"`
	File    string `json:"file,omitempty"`
	Row     int    `json:"row,omitempty"`
	Col     int    `json:"col,omitempty"`
}

type EvalErrors

type EvalErrors struct {
	Errors []EvalError
}

EvalErrors is returned by Evaluate when the policy itself is at fault: it does not parse, compile or evaluate, times out, or contains no policies.

func (*EvalErrors) Error

func (e *EvalErrors) Error() string

type EvalOutput

type EvalOutput struct {
	Title               *string            `mapstructure:"title,omitempty"`
	Description         *string            `mapstructure:"description,omitempty"`
	Remarks             *string            `mapstructure:"remarks,omitempty"`
	SkipReason          *string            `mapstructure:"skip_reason,omitempty"`
	Labels              *map[string]string `mapstructure:"labels,omitempty"`
	Violations          []Violation
	AdditionalVariables map[string]interface{}
}

EvalOutput is the decoded value of one compliance_framework policy package.

type EvaluateModulesRequest added in v0.20.0

type EvaluateModulesRequest struct {
	// Modules maps each module's file name to its source.
	Modules map[string]string
	// Input is bound to `input`.
	Input any
	// Data is merged into data.* exactly as the agent merges policy data.
	Data map[string]any
	// EvaluatedAt pins time.now_ns(). Defaults to now.
	EvaluatedAt *time.Time
}

EvaluateModulesRequest evaluates a set of Rego modules as given, for example the files of a stored policy bundle. No module name is reserved.

type EvaluateRequest

type EvaluateRequest struct {
	// Policy is the Rego source of the policy under test, stored as module policy.rego.
	Policy string `json:"policy"`
	// Modules holds extra Rego modules the policy imports, keyed by file name.
	Modules map[string]string `json:"modules,omitempty"`
	// Input is bound to `input`. Any JSON value.
	Input any `json:"input"`
	// Data is merged into data.* exactly as the agent merges policy data.
	Data map[string]any `json:"data,omitempty"`
	// EvaluatedAt pins time.now_ns(). Defaults to now.
	EvaluatedAt *time.Time `json:"evaluatedAt,omitempty"`
}

EvaluateRequest is the body of POST /api/playback/evaluate.

type EvaluateResponse

type EvaluateResponse struct {
	Results    []EvaluateResult `json:"results"`
	Prints     []string         `json:"prints"`
	DurationMs int64            `json:"durationMs"`
}

EvaluateResponse is the 200 body of POST /api/playback/evaluate.

func Evaluate

func Evaluate(ctx context.Context, req EvaluateRequest) (*EvaluateResponse, error)

Evaluate runs req in the sandbox: no I/O builtins, modules only from the request, and the caller's context deadline as the time limit.

func EvaluateModules added in v0.20.0

func EvaluateModules(ctx context.Context, req EvaluateModulesRequest) (*EvaluateResponse, error)

EvaluateModules runs req in the same sandbox as Evaluate.

type EvaluateResult

type EvaluateResult struct {
	Package             string            `json:"package"`
	File                string            `json:"file"`
	Status              string            `json:"status"`
	Title               *string           `json:"title"`
	Description         *string           `json:"description"`
	Remarks             *string           `json:"remarks"`
	SkipReason          *string           `json:"skipReason"`
	Labels              map[string]string `json:"labels"`
	Violations          []Violation       `json:"violations"`
	AdditionalVariables map[string]any    `json:"additionalVariables"`
	Raw                 map[string]any    `json:"raw"`
	// Error explains why the agent would not turn this result into evidence.
	Error string `json:"error,omitempty"`
}

EvaluateResult is one evaluated compliance_framework package.

type Evaluator

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

func NewFromBundlePath

func NewFromBundlePath(path string, policyData map[string]interface{}, opts Options) *Evaluator

NewFromBundlePath loads the policy bundle at path, as the agent does.

func NewFromModules

func NewFromModules(modules map[string]string, policyData map[string]interface{}, opts Options) *Evaluator

NewFromModules loads policies from source, keyed by file name. Nothing is read from disk.

func NewWithLoaders

func NewWithLoaders(loaders []func(r *rego.Rego), policyData map[string]interface{}, opts Options) *Evaluator

NewWithLoaders uses caller-supplied rego loader options, for example rego.ParsedBundle.

func (*Evaluator) EvalOptions

func (e *Evaluator) EvalOptions() []rego.EvalOption

EvalOptions returns the options to pass to PreparedEvalQuery.Eval. Prepared queries do not inherit rego.Time, so the pinned time is applied here.

func (*Evaluator) Execute

func (e *Evaluator) Execute(ctx context.Context, input interface{}) ([]Result, error)

Execute evaluates every package under data.compliance_framework against input.

func (*Evaluator) PrepareForEval

func (e *Evaluator) PrepareForEval(ctx context.Context, regoArgs ...func(r *rego.Rego)) (rego.PreparedEvalQuery, error)

PrepareForEval compiles the loaded policies with regoArgs, writes the policy data into a fresh store, and applies the evaluator's options.

type Options

type Options struct {
	// Capabilities restricts the builtins and features policies may use. Nil means all.
	Capabilities *ast.Capabilities
	// Time pins time.now_ns() for every evaluation. Zero means the wall clock.
	Time time.Time
	// PrintHook receives print() output. Nil disables print statements.
	PrintHook print.Hook
}

Options tunes evaluation. The zero value reproduces the agent's behaviour: every OPA builtin available, wall-clock time, and print() output discarded.

type Package

type Package string

func (Package) PurePackage

func (p Package) PurePackage() string

type Policy

type Policy struct {
	File        string
	Package     Package
	Annotations []*ast.Annotations
}

type Result

type Result struct {
	Policy Policy
	*EvalOutput
	// Raw is the package's full value as returned by OPA, before decoding.
	Raw map[string]interface{}
}

func (Result) String

func (res Result) String() string

type RuleLocation added in v0.20.0

type RuleLocation struct {
	File      string `json:"file"`
	StartLine int    `json:"startLine"`
	EndLine   int    `json:"endLine"`
}

RuleLocation is where a rule is in its module: the 1-based first and last line.

func RulesFor added in v0.20.0

func RulesFor(rules []ViolationRule, violation Violation) []RuleLocation

RulesFor returns the locations of the rules that produced violation.

type Violation

type Violation struct {
	ID          *string `json:"id,omitempty" mapstructure:"id"`
	Title       *string `json:"title,omitempty" mapstructure:"title"`
	Description *string `json:"description,omitempty" mapstructure:"description"`
	Remarks     *string `json:"remarks,omitempty" mapstructure:"remarks"`
}

type ViolationRule added in v0.20.0

type ViolationRule struct {
	Location   RuleLocation
	Violations []Violation
}

ViolationRule is one `violation` rule of a package and the violations it produced.

func LocateViolations added in v0.20.0

func LocateViolations(ctx context.Context, req EvaluateModulesRequest, pkg string) ([]ViolationRule, error)

LocateViolations reports which of pkg's `violation` rules produced which violations.

OPA merges every `violation` rule of a package into one set, so the result alone does not say where a violation came from. Each rule is copied under its own name, the copies are evaluated alongside the originals with the same input, data and time, and each copy's output is the violations its rule produced. The copies are appended after the original source, so the reported lines are those of the module as stored.

Jump to

Keyboard shortcuts

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