policyeval

package
v0.20.0-rc1 Latest Latest
Warning

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

Go to latest
Published: Sep 30, 2026 License: AGPL-3.0 Imports: 16 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 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 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.

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 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"`
}

Jump to

Keyboard shortcuts

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