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
- Variables
- func MergeData(base, overlay map[string]any) map[string]any
- func SandboxCapabilities() *ast.Capabilities
- func Status(result Result) string
- type ErrorResponse
- type EvalError
- type EvalErrors
- type EvalOutput
- type EvaluateModulesRequest
- type EvaluateRequest
- type EvaluateResponse
- type EvaluateResult
- type Evaluator
- func NewFromBundlePath(path string, policyData map[string]interface{}, opts Options) *Evaluator
- func NewFromModules(modules map[string]string, policyData map[string]interface{}, opts Options) *Evaluator
- func NewWithLoaders(loaders []func(r *rego.Rego), policyData map[string]interface{}, opts Options) *Evaluator
- type Options
- type Package
- type Policy
- type Result
- type RuleLocation
- type Violation
- type ViolationRule
Constants ¶
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, ...).
const ( StatusSatisfied = "satisfied" StatusNotSatisfied = "not-satisfied" StatusSkipped = "skipped" )
const MaxPrints = 1000
MaxPrints caps how many print() lines one evaluation returns.
const PolicyModuleName = "policy.rego"
PolicyModuleName is the module name the request's policy source is stored under.
Variables ¶
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
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.
Types ¶
type ErrorResponse ¶
type ErrorResponse struct {
Errors []EvalError `json:"errors"`
}
ErrorResponse is the 422 body of POST /api/playback/evaluate.
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 ¶
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 ¶
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 Result ¶
type Result struct {
Policy Policy
*EvalOutput
// Raw is the package's full value as returned by OPA, before decoding.
Raw map[string]interface{}
}
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 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.