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 SandboxCapabilities() *ast.Capabilities
- func Status(result Result) string
- type ErrorResponse
- type EvalError
- type EvalErrors
- type EvalOutput
- 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 Violation
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 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 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 ¶
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{}
}