Documentation
¶
Overview ¶
Package policy implements runeward's authority engine and cost/loop guardrails. Engine evaluates an Action against an ordered rule list, strictly first-match-wins: there is deliberately no deny-precedence pass, so the operator controls precedence through rule ordering. Guard caps wall-clock time, exec count, and egress while detecting failure loops.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrWallClock = errors.New("policy: wall-clock deadline exceeded") ErrMaxExecs = errors.New("policy: max execs exceeded") ErrEgressBudget = errors.New("policy: egress budget exceeded") ErrLoopDetected = errors.New("policy: runaway loop detected") )
Sentinel errors returned by Guard.
Functions ¶
This section is empty.
Types ¶
type Action ¶
type Action struct {
// Tool is the action surface, e.g. "shell", "file.read", "net".
Tool string
// Arg is the command line, path, or hostname the tool acts on.
Arg string
// Args is the raw argument vector when the tool is invoked with one (e.g.
// shell). It powers argv-aware rule matching; nil for tools without argv.
Args []string
}
Action is a single tool invocation the engine is asked to authorize.
type CELEngine ¶
type CELEngine struct {
// contains filtered or unexported fields
}
CELEngine is an authority engine backed by CEL rules. Each rule is a boolean expression over the variables `tool` and `arg`; the first rule that evaluates true wins, otherwise the default verdict applies. Safe for concurrent use: compiled programs are immutable and Eval is goroutine-safe.
type Decision ¶
type Decision struct {
Verdict profile.Verdict
Reason string
// Rule is the rule that produced this decision, nil when the engine fell
// back to its default verdict.
Rule *profile.PolicyRule
}
Decision is the outcome of evaluating an Action.
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine evaluates actions against an ordered rule set with a default verdict.
type Evaluator ¶
Evaluator renders a Decision for an Action, so the control plane can select an engine per profile without caring which is in use.
type Guard ¶
type Guard struct {
// contains filtered or unexported fields
}
Guard enforces per-session cost and loop guardrails from profile.Limits. All limits are opt-in: a zero/empty value disables that guard. Safe for concurrent use.
func NewGuard ¶
NewGuard builds a Guard from limits. It errors if WallClock or LoopWindow is set but not a valid duration string.
func (*Guard) CheckEgress ¶
CheckEgress must be called before each outbound request. It returns ErrEgressBudget once the budget is exhausted.
func (*Guard) CheckExec ¶
CheckExec must be called before each tool invocation. It checks the wall-clock deadline, a tripped loop, and the exec budget in that order, incrementing the exec counter only when the call is permitted.
func (*Guard) LoopTripped ¶
LoopTripped reports whether a failure loop has been detected and, if so, the key responsible.
func (*Guard) RecordOutcome ¶
RecordOutcome records the result of an action identified by key. A success clears the key's failure window; failures accumulate in a sliding window, and once a key hits loopThresh failures within loopWindow the detector trips and stays tripped until Reset.
type RegoEngine ¶
type RegoEngine struct {
// contains filtered or unexported fields
}
RegoEngine is an authority engine backed by an OPA/Rego module, compiled and prepared once at construction so a malformed policy fails fast. The query result may be a bare verdict string or an object {"verdict": ..., "reason": ...}; anything else falls back to the default verdict. Safe for concurrent use.
func NewRego ¶
func NewRego(module, query string, def profile.Verdict) (*RegoEngine, error)
NewRego compiles and prepares module as a RegoEngine. query defaults to "data.runeward.decision" and def to allow. Modules use Rego v1 syntax (`if`/`contains`, no future.keywords import needed).
func (*RegoEngine) Evaluate ¶
func (e *RegoEngine) Evaluate(a Action) (dec Decision)
Evaluate runs the prepared query against {tool, arg}. Evaluation errors fail closed to deny; undefined results and unrecognized verdicts return the default verdict with a nil Rule.
Source Files