Documentation
¶
Overview ¶
Package engine implements Keep's core policy evaluation.
Index ¶
Constants ¶
const ParamBody = "body"
ParamBody is the params key under which the request body is exposed to rules (params.body). It is the single source of truth shared by the call helpers that populate the body and the analysis that detects references to it.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type AuditEntry ¶
type AuditEntry struct {
Timestamp time.Time
Scope string
Operation string
AgentID string
UserID string
Direction string
Decision Decision
Rule string
Message string
RulesEvaluated []RuleResult
ParamsSummary string
// Enforced is true when the Decision was actually applied to the call.
// It is false in audit_only mode, where Decision records what would have
// happened but the call is allowed regardless.
Enforced bool
RedactSummary []RedactedField `json:",omitempty"`
}
AuditEntry is the structured log record for a single evaluation.
type Call ¶
type Call struct {
Operation string
Params map[string]any
Context CallContext
}
Call is the normalized input to the policy engine.
type CallContext ¶
type CallContext struct {
AgentID string
UserID string
Timestamp time.Time
Scope string
Direction string
Labels map[string]string
}
CallContext is metadata about who is making the call and when.
type EvalResult ¶
type EvalResult struct {
Decision Decision
Rule string
Message string
Mutations []redact.Mutation
Audit AuditEntry
}
EvalResult is the output of a policy evaluation.
type Evaluator ¶
type Evaluator struct {
// contains filtered or unexported fields
}
Evaluator runs the rule evaluation loop for a single scope.
func NewEvaluator ¶
func NewEvaluator( celEnv *keepcel.Env, scope string, mode config.Mode, onError config.ErrorMode, rules []config.Rule, aliases map[string]string, defs map[string]string, detector *secrets.Detector, caseSensitive bool, ) (*Evaluator, error)
NewEvaluator creates an evaluator for a scope. Compiles all CEL expressions and redact patterns at creation time. Returns an error if any expression fails to compile.
func (*Evaluator) Evaluate ¶
func (ev *Evaluator) Evaluate(ctx context.Context, call Call) EvalResult
Evaluate runs all rules against the given call and returns the result.
func (*Evaluator) RequiresBody ¶ added in v0.5.0
RequiresBody reports whether any compiled rule in this scope references the request body (params.body). Callers can use this to decide whether the (potentially expensive) request body needs to be buffered and supplied before evaluation. The answer is fixed at compile time and precomputed in NewEvaluator, so this is an O(1) lookup safe to call per request.
func (*Evaluator) SetJudgeFunc ¶ added in v0.4.0
func (ev *Evaluator) SetJudgeFunc(fn JudgeHandler)
SetJudgeFunc sets the judge handler for this evaluator.
type JudgeAudit ¶ added in v0.4.0
type JudgeAudit struct {
Model string `json:"model"`
Verdict string `json:"verdict"`
Reason string `json:"reason"`
Cached bool `json:"cached,omitempty"`
LatencyMS int64 `json:"latency_ms"`
Usage JudgeUsage `json:"usage"`
Error string `json:"error,omitempty"`
}
JudgeAudit records the result of a judge call.
type JudgeHandler ¶ added in v0.4.0
type JudgeHandler func(ctx context.Context, model, prompt, content string) (JudgeResult, error)
JudgeHandler is the function signature for judge evaluation.
type JudgeResult ¶ added in v0.4.0
type JudgeResult struct {
Decision string
Reason string
InputTokens int
OutputTokens int
Cached bool
}
JudgeResult holds the raw result from a judge call at the engine level.
type JudgeUsage ¶ added in v0.4.0
type JudgeUsage struct {
InputTokens int `json:"input_tokens"`
OutputTokens int `json:"output_tokens"`
}
JudgeUsage tracks token consumption for a judge call.
type RedactedField ¶
type RedactedField struct {
Path string // e.g. "params.text"
Replaced string // the post-redaction value (contains [REDACTED:...] placeholders)
}
RedactedField records what was redacted without exposing the original value.
type RuleResult ¶
type RuleResult struct {
Name string
Matched bool
Action string
Skipped bool
Error bool // true if a CEL eval error occurred for this rule
ErrorMessage string // the CEL eval error message, populated when Error is true
Judge *JudgeAudit `json:"judge,omitempty"`
}
RuleResult records what happened when a single rule was checked.
Source Files